Shipping Write

pixiCreateInvoicePackage

Creates a package (pixi.InvoicePackage) for an invoice, optionally with package lines, tracking IDs and label URLs, and returns the new PackageId.

Creates a new shipping package for an existing invoice and optionally assigns invoice lines with quantities to it.

Steps:

Checks the setting Premium_API. If it is not enabled, an error row is returned.
Empty strings in the text parameters are treated as NULL; ShipVendorCode is trimmed.
The invoice is identified by InvoiceNr and/or InvoiceKey. At least one is required. If both are given, they must point to the same invoice.
The shipping vendor is resolved from ShipVendorCode via ShipVendor.ShipVendorCode. If no code is given, the invoice's own ShipVendor is used. An explicitly given code that does not exist is rejected; if the fallback does not resolve, ShipVendorId simply stays NULL.
If Lines is given, it is parsed as XML (/Lines/Line with InvlineId and Quantity). Each line is validated:
- InvlineId and Quantity must be integers,
- no duplicate InvlineId,
- every line must belong to the invoice (Invlines.InvoiceRef),
- Quantity must be greater than 0,
- Quantity plus the quantity already allocated to other packages (pixi.InvoicePackageLines) must not exceed Invlines.ItemQty.
In a transaction the package is inserted into pixi.InvoicePackage (with TimesLabelPrinted = 0, audit columns from the user CreateEmp), the lines are inserted into pixi.InvoicePackageLines, and Invoices.Packages is incremented by 1.
If TrackingID or ReturnTrackingId is given, pixiUpdateInvoicePackageTrackingIds is executed for the new package to sync the tracking IDs to the invoice (ShipmentTrackingID, retTrackID, retTrackIDhist), controlled by Overwrite and ResetClientNotifiedFlag.
MQ events are published: PackageLabelSaved (only if a label URL was given) and InvoiceChanged with parameter CreatePackage.

The call always returns exactly one row with Status, Message and PackageId.

Notes

Requires the setting Premium_API = 1.
Validation reads use NOLOCK. Two concurrent calls for the same invoice lines can therefore both pass the quantity check and over-allocate a line.
The procedure starts its own transaction, or sets a savepoint if the caller already has an open transaction. The success row is selected before the commit.
Unexpected SQL errors are caught, the transaction (or savepoint) is rolled back, the error is logged via log.InsertError and returned as an ERROR row with the SQL error text.
The result of pixiUpdateInvoicePackageTrackingIds is captured internally and not checked. If that procedure reports a problem (e.g. status 411 because the combined tracking string on the invoice would exceed 512 characters), the package is still created and SUCCESS is returned, but the invoice tracking fields may not be updated.
A code comment says the tracking sync runs after the commit; in fact it runs inside the same transaction.
If a tracking ID contains several values separated by ;, the package itself ends up with only the last value (set by the tracking sync), while the invoice receives the full value.
ResetClientNotifiedFlag = 1 only has an effect together with a tracking ID: it sets ClientNotified = N in OrderHistory for the latest AUS status of the order lines on the invoice, so the shipment is exported again.
CreateEmp is resolved in UCS_USERS; unknown names fall back to the user pixiAdministration.
PackageDimensionId, GrossWeight and ExternalShipmentId are stored without validation.
MQ events are only sent if pixiMQ_Enabled is active and the events are configured in EventConfiguration; failures there do not change the result.

Parameters

Parameter	Type	Default	Description
`InvoiceNr`	varchar(20) string	NULL	Invoice number. Either this or `InvoiceKey` is required; if both are given they must match. Example: `RE2024001234`
`InvoiceKey`	int	NULL	Internal key of the invoice (`Invoices.InvoiceKey`). Either this or `InvoiceNr` is required. Example: `98765`
`TrackingID`	varchar(512) string	NULL	Shipment tracking ID of the package. If set, it is also synced to the invoice's `ShipmentTrackingID`. Example: `00340434161094042557`
`ReturnTrackingId`	varchar(512) string	NULL	Return tracking ID of the package. If set, it is synced to `retTrackID` and `retTrackIDhist` of the invoice. Example: `00340434161094099999`
`ShippingLabelUrl`	varchar(8000) string	NULL	URL of the shipping label. If set, the MQ event `PackageLabelSaved` is published. Example: `https://labels.example.com/ship/4711.pdf`
`ReturnLabelUrl`	varchar(8000) string	NULL	URL of the return label. If set, the MQ event `PackageLabelSaved` is published. Example: `https://labels.example.com/return/4711.pdf`
`ExternalShipmentId`	varchar(512) string	NULL	Shipment ID in an external shipping system; stored as is. Example: `SHP-2024-000815`
`GrossWeight`	decimal(9, 3) decimal	NULL	Gross weight of the package; stored as is. Example: `2.350`
`ShipVendorCode`	varchar(3) string	NULL	Code of the shipping vendor (`ShipVendor.ShipVendorCode`). If omitted, the invoice's shipping vendor is used. An unknown code causes an error. Example: `DHL`
`PackageDimensionId`	int	NULL	ID of a package dimension; stored without validation. Example: `3`
`Lines`	varchar(max) xml	NULL	Optional XML with the invoice lines and quantities contained in the package. Each `Line` needs an integer `InvlineId` (`Invlines.InvLineKey` of this invoice) and a positive integer `Quantity`. Example: `<Lines> <Line> <InvlineId>554433</InvlineId> <Quantity>2</Quantity> </Line> <Line> <InvlineId>554434</InvlineId> <Quantity>1</Quantity> </Line> </Lines>`
`ResetClientNotifiedFlag`	bit boolean	0	Passed to the tracking sync; only effective if a tracking ID is given. Allowed values `0` – Do not change `OrderHistory.ClientNotified`. `1` – Set `ClientNotified` = `N` for the latest `AUS` status of the invoice's order lines so the shipment is exported again. Example: `0`
`Overwrite`	bit boolean	0	Passed to the tracking sync; controls how `TrackingID` is written to the invoice's `ShipmentTrackingID`. Allowed values `0` – Append the tracking ID to the existing `ShipmentTrackingID` (separated by `;`) if it is not already contained. `1` – Rebuild `ShipmentTrackingID` from the tracking IDs of the other packages of the invoice plus the new tracking ID. Example: `0`
`CreateEmp`	varchar(50) string	API	User name for the audit columns; resolved in `UCS_USERS`, unknown names fall back to `pixiAdministration`. Example: `API`

Response

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

Status row of the call with the ID of the created package on success.

Column	Type	Description
`Status`	varchar(7) string	`SUCCESS` or `ERROR`.
`Message`	varchar string	Success text or error description.
`PackageId` Nullable	int	`Id` of the new row in `pixi.InvoicePackage`; `NULL` on error.

Response example

<SqlRowSet1>
  <row>
    <Status>SUCCESS</Status>
    <Message>Package created successfully.</Message>
    <PackageId>4711</PackageId>
  </row>
</SqlRowSet1>

Error messages

Status	Message	Cause
ERROR	Setting "Premium_API" is not enabled.	The setting `Premium_API` is not set to 1. Enable the Premium API in Pixi.
ERROR	At least one of @InvoiceNr or @InvoiceKey must be provided.	Neither `InvoiceNr` nor `InvoiceKey` was given (or both empty).
ERROR	Invoice not found for the given @InvoiceNr.	No invoice exists with the given `InvoiceNr`.
ERROR	@InvoiceNr and @InvoiceKey do not match.	Both identifiers were given but refer to different invoices.
ERROR	Invoice not found.	No invoice exists with the given `InvoiceKey`.
ERROR	ShipVendorCode '{ShipVendorCode}' is not a valid shipping vendor.	The given `ShipVendorCode` does not exist in `ShipVendor`. Use a valid code or omit the parameter.
ERROR	Cannot parse XML	`Lines` is not well-formed XML.
ERROR	XML contains invalid or missing InvlineId/Quantity values.	A `Line` element lacks `InvlineId` or `Quantity`, or a value is not an integer.
ERROR	XML contains duplicate InvlineId entries.	The same `InvlineId` appears more than once in `Lines`.
ERROR	InvlineId(s) {list} do not belong to the given invoice.	The listed invoice line IDs do not exist or belong to another invoice.
ERROR	Quantity for InvlineId(s) {list} must be greater than 0.	A `Quantity` of 0 or less was given for the listed lines.
ERROR	Quantity for InvlineId(s) {list} exceeds the available quantity on the invoice line.	The requested quantity plus the quantity already assigned to other packages exceeds `Invlines.ItemQty`.
ERROR	{SQL error message}	An unexpected SQL error occurred while writing; the transaction is rolled back and the error is logged.

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:pixiCreateInvoicePackage>
      <!-- <InvoiceNr>RE2024001234</InvoiceNr> -->
      <!-- <InvoiceKey>98765</InvoiceKey> -->
      <!-- <TrackingID>00340434161094042557</TrackingID> -->
      <!-- <ReturnTrackingId>00340434161094099999</ReturnTrackingId> -->
      <!-- <ShippingLabelUrl>https://labels.example.com/ship/4711.pdf</ShippingLabelUrl> -->
      <!-- <ReturnLabelUrl>https://labels.example.com/return/4711.pdf</ReturnLabelUrl> -->
      <!-- <ExternalShipmentId>SHP-2024-000815</ExternalShipmentId> -->
      <!-- <GrossWeight>2.350</GrossWeight> -->
      <!-- <ShipVendorCode>DHL</ShipVendorCode> -->
      <!-- <PackageDimensionId>3</PackageDimensionId> -->
      <!-- <Lines><![CDATA[<Lines><Line><InvlineId>554433</InvlineId><Quantity>2</Quantity></Line><Line><InvlineId>554434</InvlineId><Quantity>1</Quantity></Line></Lines>]]></Lines> -->
      <!-- <ResetClientNotifiedFlag>0</ResetClientNotifiedFlag> -->
      <!-- <Overwrite>0</Overwrite> -->
      <!-- <CreateEmp>API</CreateEmp> -->
    </ns1:pixiCreateInvoicePackage>
  </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:pixiCreateInvoicePackage>
      <!-- <InvoiceNr>RE2024001234</InvoiceNr> -->
      <!-- <InvoiceKey>98765</InvoiceKey> -->
      <!-- <TrackingID>00340434161094042557</TrackingID> -->
      <!-- <ReturnTrackingId>00340434161094099999</ReturnTrackingId> -->
      <!-- <ShippingLabelUrl>https://labels.example.com/ship/4711.pdf</ShippingLabelUrl> -->
      <!-- <ReturnLabelUrl>https://labels.example.com/return/4711.pdf</ReturnLabelUrl> -->
      <!-- <ExternalShipmentId>SHP-2024-000815</ExternalShipmentId> -->
      <!-- <GrossWeight>2.350</GrossWeight> -->
      <!-- <ShipVendorCode>DHL</ShipVendorCode> -->
      <!-- <PackageDimensionId>3</PackageDimensionId> -->
      <!-- <Lines><![CDATA[<Lines><Line><InvlineId>554433</InvlineId><Quantity>2</Quantity></Line><Line><InvlineId>554434</InvlineId><Quantity>1</Quantity></Line></Lines>]]></Lines> -->
      <!-- <ResetClientNotifiedFlag>0</ResetClientNotifiedFlag> -->
      <!-- <Overwrite>0</Overwrite> -->
      <!-- <CreateEmp>API</CreateEmp> -->
    </ns1:pixiCreateInvoicePackage>
  </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' => 'RE2024001234',
    // 'InvoiceKey' => '98765',
    // 'TrackingID' => '00340434161094042557',
    // 'ReturnTrackingId' => '00340434161094099999',
    // 'ShippingLabelUrl' => 'https://labels.example.com/ship/4711.pdf',
    // 'ReturnLabelUrl' => 'https://labels.example.com/return/4711.pdf',
    // 'ExternalShipmentId' => 'SHP-2024-000815',
    // 'GrossWeight' => '2.350',
    // 'ShipVendorCode' => 'DHL',
    // 'PackageDimensionId' => '3',
    // 'Lines' => '<Lines><Line><InvlineId>554433</InvlineId><Quantity>2</Quantity></Line><Line><InvlineId>554434</InvlineId><Quantity>1</Quantity></Line></Lines>',
    // 'ResetClientNotifiedFlag' => '0',
    // 'Overwrite' => '0',
    // 'CreateEmp' => 'API',
];

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

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

pixiUpdateInvoicePackageTrackingIds

Tables used

Settings · Read Invoices · Write ShipVendor · Read Invlines · Read InvoicePackage · Write InvoicePackageLines · Write UCS_USERS · Read OrderHistory · Write

SQL object:: dbo.pipiCreateInvoicePackage