pixiUpdateDelivery · Pixi API documentation

Updates one record in SDelHeader (supplier delivery header) and always returns exactly one row with the column ReturnMSG.

Identifying the delivery

SDelHkey and DeliveryNumber are treated as missing when they are 0. At least one of them is required.
If SDelHkey is given, it is used and DeliveryNumber is ignored.
Otherwise the delivery with SDelHNr = DeliveryNumber and the lowest key is used.

Validation

Status must be NEW, INV or CLS, or be left out (NULL), which keeps the current status. An empty string is rejected.
If ExternalReceiptNr is given, no other delivery of the same Lieferant may already carry this external receipt number.
Without PiccoUser: the delivery must exist and must not be locked by Picco (LockedByPicco is not Y).
With PiccoUser (Mobix/Picco client): the delivery must exist and either be assigned to this PiccoUser or not be locked by Picco.

Field handling

Note, extInvoiceNr and extOrderNr are trimmed. Empty or missing values keep the value already stored.
ExternalReceiptNr and Status: missing or empty values keep the stored value.
UserName defaults to API and is stored as the last updating user; the update date is set to the current time.
Picco information is always rewritten:
- Without PiccoUser, the delivery's PiccoUser and LockedByPicco are cleared.
- With PiccoUser, the user is stored and LockedByPicco is set to Y if LockDelivery = 1. If Status = CLS, both the Picco user and the lock are cleared.
SupplNr is obsolete. The supplier is never changed.

If the status actually changes, a delivery-status-changed event is published.

Notes

Note, extInvoiceNr, extOrderNr and ExternalReceiptNr cannot be cleared with this call. Empty values keep the existing content.
extOrderNr is declared as varchar(8000), but the internal update procedure accepts only varchar(1000). Longer values are truncated.
A call without PiccoUser removes an existing Picco user assignment from the delivery.
For a delivery locked by Picco, a call without PiccoUser fails with Delivery header does not exist, even though the delivery exists.
If DeliveryNumber matches no delivery, the same message is returned.
The procedure returns -1 as its return value on errors. Errors are reported only as a ReturnMSG row, not as SQL errors.
Existence checks read SDelHeader with NOLOCK. No explicit transaction is used.
On a status change, pixi_MQ_DeliveryStatusChanged_EventPublish is executed. Its definition is not attached, so the details of the published message are unknown.
The exact business meaning of the status INV is not visible in the code.

Tables used

SDelHeader · Write

Parameter	Type	Default	Description
`SDelHkey`	int	NULL	Internal key of the delivery (`SDelHKey`). `0` is treated as not given. Takes precedence over `DeliveryNumber`. Example: `15872`
`SupplNr`	varchar(4) string	NULL	Obsolete. Ignored; the Lieferant of the delivery is read from the header and never changed.
`DeliveryNumber`	int	NULL	Delivery number (`SDelHNr`). Used only if `SDelHkey` is not given; `0` is treated as not given. Example: `4711`
`Note`	varchar(8000) string	NULL	New note of the delivery. Trimmed; empty or missing keeps the stored note. Example: `Pallet damaged on arrival`
`extInvoiceNr`	varchar(25) string	NULL	External invoice number of the Lieferant. Trimmed; empty or missing keeps the stored value. Example: `RE-2024-00815`
`extOrderNr`	varchar(8000) string	NULL	External order number(s). Trimmed; empty or missing keeps the stored value. Effectively limited to 1000 characters. Example: `PO-55102`
`UserName`	varchar(50) string	NULL	User stored as last editor. Defaults to `API`. Example: `shopsync`
`PiccoUser`	varchar(59) string	NULL	Picco/Mobix user working on the delivery. Empty is treated as not given. If not given, the Picco assignment and lock are cleared. Example: `mobix01`
`Status`	varchar(3) string	NULL	New delivery status. Missing keeps the current status; an empty string is rejected. Allowed values `NEW` – New delivery `INV` – Status `INV` as defined in Pixi (meaning not visible in the code) `CLS` – Closed; also releases Picco user and lock when `PiccoUser` is given Example: `CLS`
`LockDelivery`	bit boolean	0	Only with `PiccoUser`: `1` locks the delivery for this Picco user (`LockedByPicco = Y`) unless `Status` is `CLS`. Allowed values `0` – Do not lock (an existing lock is removed) `1` – Lock the delivery for the Picco user Example: `1`
`ExternalReceiptNr`	varchar(50) string	NULL	External receipt number. Must be unique per Lieferant; empty or missing keeps the stored value. Example: `WE-778812`

Result set 1 · Always (one row; success or error message)

Status message of the call.

Column	Type	Description
`ReturnMSG`	varchar string	`Update successful` on success, otherwise the error text.

Response example

<SqlRowSet1>
  <row>
    <ReturnMSG>Update successful</ReturnMSG>
  </row>
</SqlRowSet1>

Status	Message	Cause
-1	Delivery ID or Delivery number must be provided.	Neither `SDelHkey` nor `DeliveryNumber` was given (or both are 0).
-1	Wrong status code provided.	`Status` is not `NEW`, `INV` or `CLS` (including an empty string). Omit the parameter to keep the status.
-1	For given External Receipt Number already exists an delivery.	Another delivery of the same Lieferant already has this `ExternalReceiptNr`.
-1	Delivery header does not exist	No delivery found for the key or number. Also returned without `PiccoUser` if the delivery is locked by Picco, and with `PiccoUser` if the delivery is locked by a different Picco user.

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:pixiUpdateDelivery>
      <!-- <SDelHkey>15872</SDelHkey> -->
      <!-- <SupplNr>?</SupplNr> -->
      <!-- <DeliveryNumber>4711</DeliveryNumber> -->
      <!-- <Note>Pallet damaged on arrival</Note> -->
      <!-- <extInvoiceNr>RE-2024-00815</extInvoiceNr> -->
      <!-- <extOrderNr>PO-55102</extOrderNr> -->
      <!-- <UserName>shopsync</UserName> -->
      <!-- <PiccoUser>mobix01</PiccoUser> -->
      <!-- <Status>CLS</Status> -->
      <!-- <LockDelivery>1</LockDelivery> -->
      <!-- <ExternalReceiptNr>WE-778812</ExternalReceiptNr> -->
    </ns1:pixiUpdateDelivery>
  </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:pixiUpdateDelivery>
      <!-- <SDelHkey>15872</SDelHkey> -->
      <!-- <SupplNr>?</SupplNr> -->
      <!-- <DeliveryNumber>4711</DeliveryNumber> -->
      <!-- <Note>Pallet damaged on arrival</Note> -->
      <!-- <extInvoiceNr>RE-2024-00815</extInvoiceNr> -->
      <!-- <extOrderNr>PO-55102</extOrderNr> -->
      <!-- <UserName>shopsync</UserName> -->
      <!-- <PiccoUser>mobix01</PiccoUser> -->
      <!-- <Status>CLS</Status> -->
      <!-- <LockDelivery>1</LockDelivery> -->
      <!-- <ExternalReceiptNr>WE-778812</ExternalReceiptNr> -->
    </ns1:pixiUpdateDelivery>
  </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 = [
    // 'SDelHkey' => '15872',
    // 'SupplNr' => '?',
    // 'DeliveryNumber' => '4711',
    // 'Note' => 'Pallet damaged on arrival',
    // 'extInvoiceNr' => 'RE-2024-00815',
    // 'extOrderNr' => 'PO-55102',
    // 'UserName' => 'shopsync',
    // 'PiccoUser' => 'mobix01',
    // 'Status' => 'CLS',
    // 'LockDelivery' => '1',
    // 'ExternalReceiptNr' => 'WE-778812',
];

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

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