pixiUpdateInvoicePackage · Pixi API documentation

Writes the result of a shipping provider (tracking number, label URLs, provider messages) to a package of an invoice (pixi.InvoicePackage) and to the invoice itself (dbo.Invoices).

Steps:

All string parameters that are passed as empty strings are treated as NULL (= not supplied).
The package PackageId must exist, otherwise a 400 response is returned.
If InvoiceKey is supplied, it must match the invoice of the package, otherwise a 400 response is returned. If it is omitted, the invoice of the package is used.
Package update: TrackingID, ReturnTrackingId, ExternalShipmentId, MessageFromProvider and MessageFromProviderDetail are overwritten only with supplied values; omitted values keep the stored data. ShippingLabelUrl and ReturnLabelUrl take the new value or keep the current one. For packages of a shipping vendor with external label functionality (functionality version 3) that were shipped via a toolbox station, ShippingLabelUrl is set to NO URL FROM PROVIDER if no URL exists at all. RecordModifiedOn and RecordModifiedByUserId (user API) are set.
Invoice update:
- ShipmentTrackingID: if empty, it is set to TrackingId; otherwise TrackingId is appended with ; unless the existing value already contains it.
- retTrackID / retTrackIDhist: if retTrackID is empty, retTrackID becomes ReturnTrackingId and the history is set to ReturnTrackingId;. Otherwise, if the new ID is not yet contained in retTrackID, it is appended to the history and retTrackID is replaced.
- UpdateDate and UpdateEmp (TrackingID API Import) are set.
If ResetClientNotifiedFlag = 1, the latest AUS (shipped) order history entry of every order line on the invoice is reset to ClientNotified = 'N', so the order is exported again with the tracking ID.
A row with Response = 200 OK is returned and the transaction is committed.
After the commit, MQ events are published: PackageLabelSaved (only for external label packages shipped via toolbox station, with flags whether the shipping or return label URL changed) and always InvoiceChanged with parameter SetTrackingId.

Notes

Runs in its own transaction (or a savepoint if a transaction is already open). An exclusive application lock PixiInvoicePackage (timeout 30 s) serializes the call with other package updates; if the lock cannot be acquired the update still runs.
Deadlocks (error 1205) are retried up to 5 times with a 5 ms delay. Other errors are logged via log.InsertError and answered with 500 Internal Server Error. In rare error situations after the 200 OK row (e.g. during commit or event publishing), the caller may receive more than one Response result set.
The duplicate check for tracking IDs is a substring LIKE test: an ID that is part of an existing ID (e.g. 123 in 12345) is not appended to the invoice, and % or _ in IDs act as wildcards.
InvoicePackage.TrackingID is overwritten, whereas Invoices.ShipmentTrackingID collects all IDs separated by ;.
If the invoice has no return tracking ID yet, retTrackIDhist is replaced (not appended) by the new ID.
CONTEXT_INFO is set to 0x11111 during the invoice update, presumably to influence triggers on dbo.Invoices.
Lookups use NOLOCK.
MQ events are only sent if the setting pixiMQ_Enabled is active and the events are configured and enabled in EventConfiguration.

Tables used

InvoicePackage · Write ShipVendor · Read ShipVendorFunctionality · Read Invoices · Write OrderHistory · Write Invlines · Read UCS_USERS · Read

Parameter	Type	Default	Description
`PackageId` Required	int	–	ID of the invoice package (`pixi.InvoicePackage.Id`) to update. Example: `48211`
`InvoiceKey`	int	NULL	Optional invoice key for validation. If supplied, it must match the invoice of the package; if omitted, the invoice of the package is used. Example: `1023456`
`ShippingLabelUrl`	varchar(8000) string	NULL	URL of the shipping label. Empty or omitted keeps the current URL. Example: `https://labels.example-carrier.com/label/00340434161094042557.pdf`
`TrackingId`	varchar(512) string	NULL	Tracking number of the shipment. Overwrites the package tracking ID and is appended to `Invoices.ShipmentTrackingID` if not yet contained. Example: `00340434161094042557`
`ReturnLabelUrl`	varchar(8000) string	NULL	URL of the return label. Empty or omitted keeps the current URL. Example: `https://labels.example-carrier.com/return/00340434161094042564.pdf`
`ReturnTrackingId`	varchar(512) string	NULL	Tracking number of the return label. Written to the package and to `Invoices.retTrackID` / `retTrackIDhist`. Example: `00340434161094042564`
`ExternalShipmentId`	varchar(512) string	NULL	Shipment ID at the shipping provider. Only overwritten if supplied. Example: `SHP-2024-778812`
`MessageFromProvider`	varchar(max) string	NULL	Message returned by the shipping provider. Only overwritten if supplied. Example: `Label created successfully`
`MessageFromProviderDetail`	varchar(max) string	NULL	Detailed message of the shipping provider. Only overwritten if supplied. Example: `Weight 2.4 kg, product: Paket National`
`ResetClientNotifiedFlag`	bit boolean	0	If 1, the latest `AUS` order history entries of the invoice's order lines are set to `ClientNotified = 'N'` so the shipment is exported again with the tracking ID. Allowed values `0` – Do not change the order history. `1` – Reset the client notified flag so the shipment is exported again. Example: `1`

Result set 1 · Always (one row with the outcome of the call).

HTTP-like status text of the call.

Column	Type	Description
`Response`	varchar(100) string	`200 OK` on success, otherwise a `400` or `500` message.

Response example

<SqlRowSet1>
  <row>
    <Response>200 OK</Response>
  </row>
</SqlRowSet1>

Status	Message	Cause
400	400 Bad Request - Package ID does not exist.	No invoice package with the given `PackageId` exists. Check the package ID.
400	400 Bad Request - Invoice ID does not match the package.	The supplied `InvoiceKey` differs from the invoice the package belongs to. Pass the correct key or omit the parameter.
500	500 Internal Server Error	An unexpected SQL error occurred during the update (or a deadlock persisted after 5 retries). The changes are rolled back and the error is logged.

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:pixiUpdateInvoicePackage>
      <PackageId>48211</PackageId>
      <!-- <InvoiceKey>1023456</InvoiceKey> -->
      <!-- <ShippingLabelUrl>https://labels.example-carrier.com/label/00340434161094042557.pdf</ShippingLabelUrl> -->
      <!-- <TrackingId>00340434161094042557</TrackingId> -->
      <!-- <ReturnLabelUrl>https://labels.example-carrier.com/return/00340434161094042564.pdf</ReturnLabelUrl> -->
      <!-- <ReturnTrackingId>00340434161094042564</ReturnTrackingId> -->
      <!-- <ExternalShipmentId>SHP-2024-778812</ExternalShipmentId> -->
      <!-- <MessageFromProvider>Label created successfully</MessageFromProvider> -->
      <!-- <MessageFromProviderDetail>Weight 2.4 kg, product: Paket National</MessageFromProviderDetail> -->
      <!-- <ResetClientNotifiedFlag>1</ResetClientNotifiedFlag> -->
    </ns1:pixiUpdateInvoicePackage>
  </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:pixiUpdateInvoicePackage>
      <PackageId>48211</PackageId>
      <!-- <InvoiceKey>1023456</InvoiceKey> -->
      <!-- <ShippingLabelUrl>https://labels.example-carrier.com/label/00340434161094042557.pdf</ShippingLabelUrl> -->
      <!-- <TrackingId>00340434161094042557</TrackingId> -->
      <!-- <ReturnLabelUrl>https://labels.example-carrier.com/return/00340434161094042564.pdf</ReturnLabelUrl> -->
      <!-- <ReturnTrackingId>00340434161094042564</ReturnTrackingId> -->
      <!-- <ExternalShipmentId>SHP-2024-778812</ExternalShipmentId> -->
      <!-- <MessageFromProvider>Label created successfully</MessageFromProvider> -->
      <!-- <MessageFromProviderDetail>Weight 2.4 kg, product: Paket National</MessageFromProviderDetail> -->
      <!-- <ResetClientNotifiedFlag>1</ResetClientNotifiedFlag> -->
    </ns1:pixiUpdateInvoicePackage>
  </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' => '48211',
    // 'InvoiceKey' => '1023456',
    // 'ShippingLabelUrl' => 'https://labels.example-carrier.com/label/00340434161094042557.pdf',
    // 'TrackingId' => '00340434161094042557',
    // 'ReturnLabelUrl' => 'https://labels.example-carrier.com/return/00340434161094042564.pdf',
    // 'ReturnTrackingId' => '00340434161094042564',
    // 'ExternalShipmentId' => 'SHP-2024-778812',
    // 'MessageFromProvider' => 'Label created successfully',
    // 'MessageFromProviderDetail' => 'Weight 2.4 kg, product: Paket National',
    // 'ResetClientNotifiedFlag' => '1',
];

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

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