pixiSetOrderShippingLock

Sets the shipping lock (ASlocked) on the delivery address of an order.

Locked = NULL is treated as 1; an empty or NULL UserName becomes API.
The delivery address reference (ShipAdrRef) is read from OrderHeader for OrderNr. If the order does not exist, or its ShipAdrRef is NULL, an ERROR row is returned.
The referenced record in Addresses is selected only if it has AddrType = 'S' and its current ASlocked value differs from the target value (Y for lock, N for unlock). If no such address is found, an INFO row is returned and nothing is changed.
If Reason is empty or NULL, it is replaced with Order was locked by {UserName} or Order was unlocked by {UserName}.
A record is inserted into pixi.AddressesShippingLockHistory. It holds the user ID, the address key, the lock flag and the reason. The user ID is resolved from UserName via inf.UserGetByName, which falls back to the pixiAdministration user if the name is unknown.
The address is updated:
- ASlocked is set to Y/N.
- UpdateDate is set to the current time.
- UpdateEmp is set to the user name. The default API is written as API SetOrderShippingLock.
An OK row is returned.

Notes

The lock is stored on the address record referenced by the order's ShipAdrRef, not on the order header itself.
The INFO row (already set to …) is also returned when the referenced address does not exist or does not have AddrType = 'S'. In that case the message can be misleading.
OrderHeader is read with NOLOCK; the address is selected with UPDLOCK.
No explicit transaction is used. The history insert and the address update are separate statements, so they are not rolled back together.
During the update, CONTEXT_INFO is temporarily set to 0x33999 and restored afterwards. This is presumably evaluated by triggers on Addresses, which are not attached.
Status rows always use the column name ErrorMessage, also for the OK case.

Tables used

OrderHeader · Read Addresses · Write AddressesShippingLockHistory · Write UCS_USERS · Read

Parameter	Type	Default	Description
`OrderNr` Required	int	–	Number of the order whose shipping lock is changed. Example: `104523`
`Locked`	bit boolean	1	Target state of the shipping lock. `NULL` is treated as `1`. Allowed values `1` – Set the shipping lock (`ASlocked` = `Y`). `0` – Remove the shipping lock (`ASlocked` = `N`). Example: `1`
`UserName`	varchar(50) string	API	Name of the user making the change. Empty or `NULL` becomes `API`. It is used to resolve the user ID for the history entry, falling back to `pixiAdministration`. It is also written to `UpdateEmp`, where `API` is stored as `API SetOrderShippingLock`. Example: `shopsync`
`Reason`	varchar(255) string	–	Reason stored as `CustomerComment` in the shipping lock history. If empty, a default text `Order was locked by …` / `Order was unlocked by …` is used. Example: `Payment not yet received`

Result set 1 · If no order with `OrderNr` exists (or it has no delivery address reference)

Error status row.

Column	Type	Description
`ReturnCode`	varchar(5) string	Always `ERROR`.
`ErrorMessage` Nullable	varchar(48) string	Error text including the order number.

Result set 2 · If the delivery address already has the target lock state, does not exist or is not of type `S`

Information status row; nothing is changed.

Column	Type	Description
`ReturnCode`	varchar(4) string	Always `INFO`.
`ErrorMessage` Nullable	varchar(70) string	Text stating that the order is already set to `Y` or `N`.

Result set 3 · On success

Success status row after the history entry was written and the address updated.

Column	Type	Description
`ReturnCode`	varchar(2) string	Always `OK`.
`ErrorMessage` Nullable	varchar(50) string	Confirmation text including the order number.

Response example

<SqlRowSet1>
  <row>
    <ReturnCode>OK</ReturnCode>
    <ErrorMessage>Order with OrderNr 104523 changed. </ErrorMessage>
  </row>
</SqlRowSet1>

Status	Message	Cause
ERROR	No Order found with OrderNR {OrderNr}	No order with the given `OrderNr` exists in `OrderHeader`, or its `ShipAdrRef` is `NULL`. Pass a valid order number.
INFO	Order with OrderNr {OrderNr} is already set to {Y\|N}.	The delivery address already has the requested lock state. The same row is returned if the referenced address does not exist or is not of type `S`. No change is made.

POST https://apigateway.descartes.com/tms/pixi/
Content-Type: text/xml; charset=utf-8
Authorization: Basic BASE64(USERNAME:PASSWORD)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiSetOrderShippingLock>
      <OrderNr>104523</OrderNr>
      <!-- <Locked>1</Locked> -->
      <!-- <UserName>shopsync</UserName> -->
      <!-- <Reason>Payment not yet received</Reason> -->
    </ns1:pixiSetOrderShippingLock>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

curl -X POST 'https://apigateway.descartes.com/tms/pixi/' \
  --user 'USERNAME:PASSWORD' \
  --header 'Content-Type: text/xml; charset=utf-8' \
  --data-binary @- <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiSetOrderShippingLock>
      <OrderNr>104523</OrderNr>
      <!-- <Locked>1</Locked> -->
      <!-- <UserName>shopsync</UserName> -->
      <!-- <Reason>Payment not yet received</Reason> -->
    </ns1:pixiSetOrderShippingLock>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML

<?php

$soapClient = new SoapClient(null, [
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
    'location' => 'https://apigateway.descartes.com/tms/pixi/',
    'uri' => 'https://apigateway.descartes.com/tms/pixi/',
]);

$arguments = [
    'OrderNr' => '104523',
    // 'Locked' => '1',
    // 'UserName' => 'shopsync',
    // 'Reason' => 'Payment not yet received',
];

$soapArguments = [];
foreach ($arguments as $name => $value) {
    $soapArguments[] = new SoapVar($value, XSD_STRING, '', '', $name);
}

$response = $soapClient->__soapCall('pixiSetOrderShippingLock', $soapArguments);