Shipping Write

pixiInvoiceSetTrackingIDforPolling

Sets one or more shipment tracking IDs on an invoice and its packages, optionally replacing existing packages and re-flagging the order for shipping notification export.

Stores tracking IDs for an invoice. The call returns no result set.

1. Finding the invoice

The invoice is looked up in Invoices by InvoiceNR.
The call also tries shortened numbers. It removes suffixes after the last -, one at a time: R1001-2-1, then R1001-2, then R1001. All matching numbers are checked.
If no invoice matches, nothing is changed and the call ends without an error.

2. Separator

If Separator is not ; and not empty, every occurrence of it in TrackingID is replaced by ;.
TrackingID can therefore hold several tracking IDs, for example separated by , or |.

3. Overwrite (Overwrite = 1)

All invoice packages (pixi.InvoicePackage) of the invoice are deleted, together with their package lines (pixi.InvoicePackageLines).
References to these packages in InvoicePolling are set to NULL.

4. Setting the tracking IDs

The internal procedure Pixi_SetTrackingId is called. It splits the list and ignores tracking IDs that are already stored in Invoices.ShipmentTrackingID.

If the invoice has no packages with items from a packing station:

If the invoice has exactly one package and it has no tracking ID yet, that package gets the first new ID.
Every further new ID creates a new package.
ShipmentTrackingID of the invoice is rebuilt from the distinct tracking IDs of all its packages, sorted and separated by ;.

If the invoice has packages with items:

With exactly one package, that package gets the last new ID.
With several packages, the packages are not changed.
ShipmentTrackingID becomes the union of the existing and the new IDs.

In both cases the invoice also gets:

Packages set to the number of packages;
UpdateDate and UpdateEmp (TrackingID Import) set;
an InvoiceChanged event published.

5. Re-export (ResetClientNotifiedFlag = 1)

For each order line on the invoice, the latest OrderHistory entry with status AUS is selected.
Its ClientNotified flag is set to N.
The shipping status is then exported again, now including the tracking ID.

Notes

Transaction: The call runs in its own transaction, or in a savepoint if a transaction is already open.
Errors are not reported: Errors are caught and written to the Pixi error log (log.InsertError). They are not raised to the caller, so a failed call looks like a successful one.
Unknown invoice: An unknown invoice number is silently ignored.
Suffix lookup: If several numbers match during the lookup, the variable assignment over an ordered result usually keeps the last row. That is the shortest matching number, for example the main invoice R1001 rather than R1001-2. Avoid ambiguous numbers.
Pitfall with Overwrite: Packages are deleted, but tracking IDs already stored in Invoices.ShipmentTrackingID are still treated as existing and are not imported again. If such IDs are passed again together with Overwrite = 1, they are not recreated as packages. They can disappear from ShipmentTrackingID, which may even become NULL.
Several packages with items: If the invoice has several packages with items, no package gets the new tracking IDs; only the invoice header is updated. The internal procedure itself recommends setting tracking IDs per package instead.
Splitting: Single tracking IDs are truncated to 512 characters. Splitting is done by dbo.fPixi_GetCommaSplit, which is not attached.
Locking hints: Reads use NOLOCK, writes use ROWLOCK.

Parameters

Parameter	Type	Default	Description
`InvoiceNR` Required	varchar(20) string	–	Invoice number. Suffixes after `-` are stripped step by step if the full number does not exist. Example: `RE100234`
`TrackingID` Required	varchar(512) string	–	One or more tracking IDs, separated by `Separator`. Example: `00340434161094042557;00340434161094042558`
`Overwrite`	bit boolean	0	If 1, all existing packages and package lines of the invoice are deleted before the tracking IDs are set. Allowed values `0` – Keep existing packages and add the new tracking IDs. `1` – Delete existing packages first. Example: `0`
`ResetClientNotifiedFlag`	bit boolean	0	If 1, the latest `AUS` order history entries of the invoiced order lines get `ClientNotified` = `N`, so they are exported again. Allowed values `0` – Do not change the order history. `1` – Mark shipping status for re-export. Example: `1`
`Separator`	varchar(1) string	;	Character that separates several tracking IDs in `TrackingID`. It is converted to `;` internally. Example: `;`

Response

This call returns no result set.

Examples

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:pixiInvoiceSetTrackingIDforPolling>
      <InvoiceNR>RE100234</InvoiceNR>
      <TrackingID>00340434161094042557;00340434161094042558</TrackingID>
      <!-- <Overwrite>0</Overwrite> -->
      <!-- <ResetClientNotifiedFlag>1</ResetClientNotifiedFlag> -->
      <!-- <Separator>;</Separator> -->
    </ns1:pixiInvoiceSetTrackingIDforPolling>
  </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:pixiInvoiceSetTrackingIDforPolling>
      <InvoiceNR>RE100234</InvoiceNR>
      <TrackingID>00340434161094042557;00340434161094042558</TrackingID>
      <!-- <Overwrite>0</Overwrite> -->
      <!-- <ResetClientNotifiedFlag>1</ResetClientNotifiedFlag> -->
      <!-- <Separator>;</Separator> -->
    </ns1:pixiInvoiceSetTrackingIDforPolling>
  </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' => 'RE100234',
    'TrackingID' => '00340434161094042557;00340434161094042558',
    // 'Overwrite' => '0',
    // 'ResetClientNotifiedFlag' => '1',
    // 'Separator' => ';',
];

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

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

Tables used

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

SQL object:: dbo.pipiInvoiceSetTrackingIDforPolling