pixiInvoiceSetTrackingID · Pixi API documentation

Assigns one or more tracking IDs to an invoice (Invoices.ShipmentTrackingID) and its packages (pixi.InvoicePackage).

Invoice lookup: InvoiceNR is matched against Invoices.InvoiceNr. If it contains -, suffixes after the last - are stripped one at a time and every shortened variant is also tried (for example RE1000-2-1 → RE1000-2 → RE1000). Only invoice numbers that actually exist are used.
Separator: if Separator is not ; and not empty, every occurrence of it in TrackingID is replaced by ;. Internally ; is always used as the delimiter.
If no invoice is found, the row InvoiceNR is not existing is returned and nothing is changed.
If the invoice is found, the row InvoiceNR found and Updated is returned first. Then:
- Overwrite = 1: Invoices.ShipmentTrackingID is cleared. All packages of the invoice that have no package lines are detached from InvoicePolling (InvoicePackageId set to NULL). Packages without package lines are deleted, except the package with the lowest Id.
- The internal procedure Pixi_SetTrackingId is executed. It splits the tracking IDs, ignores IDs already stored on the invoice and distributes the new IDs to packages:
  - If no package has package lines from a packing station, a single existing package with an empty tracking ID receives the first new ID. All other new IDs, or all new IDs if no such package exists, are inserted as new packages. ShipmentTrackingID on the invoice is then rebuilt from all distinct package tracking IDs, sorted and separated by ;.
  - If packages with package lines exist and there is exactly one package, that package receives the last new ID. If there are several packages, the packages are left unchanged. ShipmentTrackingID becomes the union of the existing and the new IDs.
  - Invoices.Packages is set to the number of packages, and UpdateDate and UpdateEmp (TrackingID Import) are updated. An InvoiceChanged event is published.
- ResetClientNotifiedFlag = 1: for all order lines on the invoice, the most recent OrderHistory entry with status AUS gets ClientNotified = 'N'. The shipment is then reported to the client or shop again with the tracking ID.

Notes

The procedure runs in its own transaction, or in a savepoint if a transaction is already open.
Errors are swallowed: they are caught, the transaction is rolled back and the error is logged via log.InsertError. No error is raised to the caller. Because the message InvoiceNR found and Updated is selected before the changes are made, it can be returned even though all changes were rolled back.
Invoice number resolution: if several variants match (e.g. RE1000-1 and RE1000), the result of the ordered variable assignment typically picks the shortest matching number. Pass the exact invoice number to avoid ambiguity.
Overwrite does not reset the tracking ID of the package that is kept (lowest Id). If that package already has a tracking ID, the new IDs are added as additional packages, and the old ID reappears in ShipmentTrackingID, which is rebuilt from all packages.
Overwrite detaches InvoicePolling rows also from the kept package if it has no package lines.
Packages with package lines are never deleted. If several such packages exist, package tracking IDs are not changed at all; only the invoice field is extended. The internal procedure itself warns that tracking IDs should preferably be set per package.
Tracking IDs are truncated to 512 characters each. Splitting is done by dbo.fPixi_GetCommaSplit, the user lookup by inf.UserGetByName and event publishing by dbo.Pixi_MQ_EventPublish. Their definitions are not attached.
Lookups use NOLOCK; updates use ROWLOCK.

Tables used

Invoices · Write InvoicePackage · Write InvoicePackageLines · Read InvoicePolling · Write OrderHistory · Write Invlines · Read

Parameter	Type	Default	Description
`InvoiceNR` Required	varchar(20) string	–	Invoice number. Suffixes separated by `-` are stripped step by step if the full number does not exist. Example: `RE1004711`
`TrackingID` Required	varchar(8000) string	–	One or more tracking IDs separated by `Separator`. Each ID is truncated to 512 characters. Example: `00340434161094042557;00340434161094042564`
`Overwrite`	bit boolean	0	If 1, the invoice tracking field is cleared and packages without package lines (except the first one) are deleted before the new IDs are set. Allowed values `0` – Add new tracking IDs to the existing ones `1` – Replace existing tracking IDs (see notes for limitations) Example: `0`
`ResetClientNotifiedFlag`	bit boolean	0	If 1, the latest `AUS` entry in the order history of each order line on the invoice is set to `ClientNotified = 'N'`, so that the shipment is exported again. Allowed values `0` – Leave the order history unchanged `1` – Reset the client-notified flag of the latest shipping status Example: `1`
`Separator`	varchar(1) string	;	Delimiter used in `TrackingID`. It is converted to `;` internally; an empty value means `;`. Example: `,`

Result set 1 · Always, one row (unless an error occurs before the lookup)

Status message indicating whether the invoice was found.

Column	Type	Description
`ReturnMessage`	varchar(27) string	`InvoiceNR found and Updated` or `InvoiceNR is not existing`

Response example

<SqlRowSet1>
  <row>
    <ReturnMessage>InvoiceNR found and Updated</ReturnMessage>
  </row>
</SqlRowSet1>

Status	Message	Cause
ReturnMessage	InvoiceNR is not existing	Neither the given invoice number nor any of its variants with stripped `-` suffixes exists in `Invoices`. Check the invoice number.

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:pixiInvoiceSetTrackingID>
      <InvoiceNR>RE1004711</InvoiceNR>
      <TrackingID>00340434161094042557;00340434161094042564</TrackingID>
      <!-- <Overwrite>0</Overwrite> -->
      <!-- <ResetClientNotifiedFlag>1</ResetClientNotifiedFlag> -->
      <!-- <Separator>,</Separator> -->
    </ns1:pixiInvoiceSetTrackingID>
  </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:pixiInvoiceSetTrackingID>
      <InvoiceNR>RE1004711</InvoiceNR>
      <TrackingID>00340434161094042557;00340434161094042564</TrackingID>
      <!-- <Overwrite>0</Overwrite> -->
      <!-- <ResetClientNotifiedFlag>1</ResetClientNotifiedFlag> -->
      <!-- <Separator>,</Separator> -->
    </ns1:pixiInvoiceSetTrackingID>
  </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 = [
    'InvoiceNR' => 'RE1004711',
    'TrackingID' => '00340434161094042557;00340434161094042564',
    // 'Overwrite' => '0',
    // 'ResetClientNotifiedFlag' => '1',
    // 'Separator' => ',',
];

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

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