pixiUpdateInvoicePackageTrackingIds · Pixi API documentation

Updates tracking information on a Rechnung (Invoices) and its package (pixi.InvoicePackage). The result is always one status row with Status and Message.

Validation

At least one of PackageId or InvoiceNr and at least one of TrackingId or ReturnTrackingId must be filled. Otherwise status 400 is returned. A PackageId of 0 counts as empty.
One leading and one trailing ; is removed from TrackingId and ReturnTrackingId.

Finding invoice and package

With InvoiceNr, the invoice is read by its number. All packages with Id = PackageId or belonging to that invoice are loaded.
With only PackageId, the package is loaded and its invoice is read.
If only InvoiceNr is sent, the invoice has more than one package and Overwrite = 1, status 400 is returned (PackageId is required).
If no package is found, status 400 is returned. This also happens when the invoice does not exist or has no package. The same applies if PackageId and InvoiceNr are both sent but the package does not belong to the invoice.
If the combined length of the stored value and the new value exceeds 512 characters, status 411 is returned. This is checked for ShipmentTrackingID and for retTrackIDhist.

Which records are updated

The invoice is always updated.
The package is also updated in three cases:
- PackageId and InvoiceNr match.
- Only InvoiceNr is sent and the invoice has exactly one package.
- Only PackageId is sent.
If only InvoiceNr is sent, the invoice has several packages and Overwrite = 0, only the invoice is updated.

Shipment tracking (TrackingId)

Overwrite = 0: TrackingId is appended to Invoices.ShipmentTrackingID, separated by ;. This only happens if the existing value does not already contain it (substring match).
Overwrite = 1: ShipmentTrackingID is rebuilt from the tracking IDs of all other packages of the invoice, each followed by ;, plus TrackingId. If TrackingId is already contained in the sibling list, ShipmentTrackingID becomes TrackingId alone.
The package gets only the last ;-separated segment of TrackingId as its TrackingID.

Return tracking (ReturnTrackingId)

Overwrite does not affect return tracking.
If ReturnTrackingId is not yet contained in Invoices.retTrackID:
- retTrackID is set to its last ;-separated segment.
- The full value plus a trailing ; is appended to retTrackIDhist.
The package gets the last segment as its ReturnTrackingId.

Further steps

The invoice gets UpdateDate = GETDATE() and UpdateEmp = '(Return) TrackingID API Update'.
The package gets RecordModifiedOn and RecordModifiedByUserId, the ID of the user API.
With ResetClientNotifiedFlag = 1, ClientNotified is set to N on the latest AUS (shipped) OrderHistory entry of each order line on the invoice. The shipment is then exported or notified again.
Finally the MQ event InvoiceChanged is published with the invoice key and the parameter SetTrackingId.

Notes

Transaction: all changes run in one transaction. A savepoint is used if the caller already has an open transaction. Validation errors (400/411) change nothing; the transaction is still committed and the status row is returned.
Unexpected SQL errors: the transaction is rolled back and the error is written via log.InsertError. No status row is returned in this case.
Status as string: Status is a string (200, 400, 411), not an HTTP status. The SOAP call itself succeeds.
Duplicate check: the check for an existing tracking ID is a LIKE '%…%' substring match. A new ID that is part of an existing longer ID, or that contains % / _, may wrongly be treated as already present and not be appended.
Messages: they mention InvoiceKey, but the parameter is PackageId.
NOLOCK: invoices and packages are read with NOLOCK.
Triggers: CONTEXT_INFO is set to 0x11111 during the invoice update, presumably so that triggers can recognise this update. Their behaviour is not visible here.
Unknown API user: if no user API exists in UCS_USERS, RecordModifiedByUserId is set to NULL.
MQ event: InvoiceChanged is only sent if the setting pixiMQ_Enabled is active and the event is configured and enabled in EventConfiguration. Delivery failures are queued in EventQueue and do not cause an error in this call.

Tables used

Invoices · Write InvoicePackage · Write OrderHistory · Write Invlines · Read

Parameter	Type	Default	Description
`PackageId`	int	NULL	ID of the invoice package (`pixi.InvoicePackage.Id`). Required if `InvoiceNr` is not sent. Also required when the invoice has several packages and `Overwrite = 1`. `0` counts as empty. Example: `15832`
`InvoiceNr`	varchar(20) string	NULL	Invoice number (`Invoices.InvoiceNr`). Required if `PackageId` is not sent. If both are sent, the package must belong to this invoice. Example: `RE2024001234`
`TrackingId`	varchar(512) string	NULL	Shipment tracking ID, optionally several IDs separated by `;`. The value goes into `Invoices.ShipmentTrackingID`. The package receives the last segment. Either this or `ReturnTrackingId` must be filled. Example: `00340434161094042557`
`ReturnTrackingId`	varchar(512) string	NULL	Return tracking ID, optionally several IDs separated by `;`. The last segment is stored in `Invoices.retTrackID` and in the package. The full value is appended to `retTrackIDhist`. Example: `00340434161094042564`
`Overwrite`	bit boolean	0	Controls how `TrackingId` is written to the invoice. It has no effect on the return tracking ID. Allowed values `0` – Append `TrackingId` to the existing `ShipmentTrackingID` if not yet contained. With several packages and no `PackageId`, only the invoice is updated. `1` – Rebuild `ShipmentTrackingID` from the tracking IDs of the other packages plus `TrackingId`. With several packages, `PackageId` is required. Example: `0`
`ResetClientNotifiedFlag`	bit boolean	0	If `1`, sets `ClientNotified = 'N'` on the latest `AUS` order history entries of the invoice's order lines, so that the shipment is exported/notified again. Allowed values `0` – Do not change the order history. `1` – Reset the client notified flag of the shipped status entries. Example: `1`

Result set 1 · Always, unless an unexpected SQL error occurs

Status row with the result of the update.

Column	Type	Description
`Status`	varchar(50) string	`200` on success, `400` for invalid or missing parameters or records not found, `411` if the 512-character limit would be exceeded.
`Message`	varchar(2000) string	Success or error message.

Response example

<SqlRowSet1>
  <row>
    <Status>200</Status>
    <Message>TrackingId &amp; ReturnTrackingId was updated successfully</Message>
  </row>
</SqlRowSet1>

Status	Message	Cause
400	InvoiceKey and InvoiceNr are empty, you have to specified at least one parameter.	Neither `PackageId` nor `InvoiceNr` was sent (or `PackageId` is 0). Send at least one of them.
400	TrackingId and ReturnTrackingId are empty, you have to specified at least one parameter.	Neither `TrackingId` nor `ReturnTrackingId` was sent. Send at least one of them.
400	All parameters are empty, please review and adapt parameters.	`PackageId`, `InvoiceNr`, `TrackingId` and `ReturnTrackingId` are all empty.
400	Multiple packages found for this invoice. PackageId parameter is required to identify the specific package to update.	Only `InvoiceNr` was sent with `Overwrite = 1`, and the invoice has more than one package. Also send `PackageId`, or use `Overwrite = 0`, which updates only the invoice.
411	TrackingId or ReturnTrackingId are too long, field size max. of 512 characters was reached. Please review and adapt.	The existing `ShipmentTrackingID` or `retTrackIDhist` plus the new value would exceed 512 characters. Use shorter values or `Overwrite = 1`; the latter only helps for `TrackingId`.
400	TrackingId or ReturnTrackingId could not be updated, please check if the InvoiceKey OR InvoiceNr is correct.	No package was found for the given `PackageId`/`InvoiceNr`. This includes an unknown invoice and an invoice without packages. It also occurs if the given package does not belong to the given invoice.

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:pixiUpdateInvoicePackageTrackingIds>
      <!-- <PackageId>15832</PackageId> -->
      <!-- <InvoiceNr>RE2024001234</InvoiceNr> -->
      <!-- <TrackingId>00340434161094042557</TrackingId> -->
      <!-- <ReturnTrackingId>00340434161094042564</ReturnTrackingId> -->
      <!-- <Overwrite>0</Overwrite> -->
      <!-- <ResetClientNotifiedFlag>1</ResetClientNotifiedFlag> -->
    </ns1:pixiUpdateInvoicePackageTrackingIds>
  </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:pixiUpdateInvoicePackageTrackingIds>
      <!-- <PackageId>15832</PackageId> -->
      <!-- <InvoiceNr>RE2024001234</InvoiceNr> -->
      <!-- <TrackingId>00340434161094042557</TrackingId> -->
      <!-- <ReturnTrackingId>00340434161094042564</ReturnTrackingId> -->
      <!-- <Overwrite>0</Overwrite> -->
      <!-- <ResetClientNotifiedFlag>1</ResetClientNotifiedFlag> -->
    </ns1:pixiUpdateInvoicePackageTrackingIds>
  </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 = [
    // 'PackageId' => '15832',
    // 'InvoiceNr' => 'RE2024001234',
    // 'TrackingId' => '00340434161094042557',
    // 'ReturnTrackingId' => '00340434161094042564',
    // 'Overwrite' => '0',
    // 'ResetClientNotifiedFlag' => '1',
];

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

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