pixiGetInvoicePackage · Pixi API documentation

Reads the packages stored for an invoice in pixi.InvoicePackage, together with the package dimension code, the external order number and the invoice number.

Parameter handling and checks (each failed check returns a single Status/Message row with Status = Error):

An empty InvoiceNumber is treated as NULL. At least one of InvoiceNumber, InvoiceId, PackageId must be given.
InvoiceNumber is resolved to an invoice ID (first match on InvoiceNr).
If InvoiceId or the resolved ID is set, at least one of them must exist in Invoices.
If PackageId is given, the package must exist.
If InvoiceId and InvoiceNumber point to different invoices, the call fails.
If both a package and an invoice are given, the package must belong to that invoice.

Selection

The effective invoice is InvoiceId, otherwise the invoice resolved from InvoiceNumber.
Returned are all packages where the package ID equals PackageId or the invoice ID equals the effective invoice. If an invoice is given, all of its packages are returned, even if PackageId is also given. If only PackageId is given, only that package is returned.
InvoiceNr and OrderNrExternal are the same in every row. They are taken from the invoice (given directly or via the package) that is linked to order lines: OrderNrExternal comes from the order with the highest Order_Id of the invoice lines.
No sort order is defined.

If no package matches, an Info row is returned.

Notes

All reads use NOLOCK, so uncommitted data can be returned.
The response shape differs: on error or when nothing is found, a Status/Message row is returned instead of package rows. Check for a Status column.
An invoice number that does not exist is not reported as an error when no InvoiceId is given. Without PackageId the call then returns the Info row. With PackageId it returns only that package.
If InvoiceId does not exist but InvoiceNumber is valid, the error is the "Two different invoices" message, not "No invoice found".
An invoice is ignored for InvoiceNr/OrderNrExternal if it has no invoice lines or if any of its invoice lines has no order line reference. In that case both columns are NULL, but the packages are still returned.
The return value is 1 on error and 0 otherwise. It is not part of the SOAP result rows.

Tables used

Invoices · Read InvoicePackage · Read Invlines · Read Orderlines · Read OrderHeader · Read PackageDimension · Read

Parameter	Type	Default	Description
`InvoiceNumber`	varchar(20) string	NULL	Invoice number (`InvoiceNr`) of the invoice whose packages are requested. An empty string is treated as `NULL`. Example: `RE2024-001234`
`InvoiceId`	int	NULL	Internal invoice ID (`InvoiceKey`). Takes precedence over the ID resolved from `InvoiceNumber`. Both must point to the same invoice if both are given. Example: `98765`
`PackageId`	int	NULL	ID of a package in `pixi.InvoicePackage`. If an invoice is also given, the package must belong to it. Example: `4321`

Result set 1 · On success, if at least one package matches

One row per matching invoice package.

Column	Type	Description
`PackageId`	int	ID of the package.
`InvoiceId` Nullable	int	ID of the invoice the package belongs to.
`GrossWeight` Nullable	money decimal	Gross weight of the package.
`ShippingLabelUrl` Nullable	varchar(8000) string	URL of the shipping label.
`TrackingId` Nullable	varchar(512) string	Tracking ID of the shipment.
`TimesLabelPrinted` Nullable	tinyint int	Number of times the label has been printed.
`ReturnLabelUrl` Nullable	varchar(8000) string	URL of the return label.
`ReturnTrackingId` Nullable	varchar(512) string	Tracking ID of the return shipment.
`PackageDimensionId` Nullable	int	ID of the package dimension.
`ExternalShipmentId` Nullable	varchar(512) string	Shipment ID at the shipping provider.
`MessageFromProvider` Nullable	varchar(max) string	Message returned by the shipping provider.
`MessageFromProviderDetail` Nullable	varchar(max) string	Detailed message from the shipping provider.
`OrderNrExternal` Nullable	varchar(50) string	External order number of the order with the highest `Order_Id` linked via the invoice lines. Same value in all rows.
`InvoiceNr` Nullable	varchar(20) string	Invoice number of the determined invoice. Same value in all rows. `NULL` if the invoice has no invoice lines or a line without an order line reference.
`PackageDimensionCode` Nullable	nvarchar(100) string	Code of the package dimension from `pixi.PackageDimension`.

Result set 2 · If no package matches the parameters

Info row instead of package rows.

Column	Type	Description
`Status`	varchar(4) string	Always `Info`.
`Message`	varchar(41) string	Info text.

Result set 3 · If a parameter check fails

Error row. The procedure stops after it.

Column	Type	Description
`Status`	varchar(5) string	Always `Error`.
`Message` Nullable	varchar string	Error text.

Response example

<SqlRowSet1>
  <row>
    <PackageId>4321</PackageId>
    <InvoiceId>98765</InvoiceId>
    <GrossWeight>2.3500</GrossWeight>
    <ShippingLabelUrl>https://labels.example.com/4321.pdf</ShippingLabelUrl>
    <TrackingId>00340434161094042557</TrackingId>
    <TimesLabelPrinted>1</TimesLabelPrinted>
    <ReturnLabelUrl>https://labels.example.com/4321-return.pdf</ReturnLabelUrl>
    <ReturnTrackingId>00340434161094042558</ReturnTrackingId>
    <PackageDimensionId>3</PackageDimensionId>
    <ExternalShipmentId>SHP-778899</ExternalShipmentId>
    <MessageFromProvider>OK</MessageFromProvider>
    <OrderNrExternal>SHOP-100045</OrderNrExternal>
    <InvoiceNr>RE2024-001234</InvoiceNr>
    <PackageDimensionCode>M</PackageDimensionCode>
  </row>
</SqlRowSet1>

Status	Message	Cause
Error	At least one of the parameters needs to be provided	`InvoiceNumber` (or empty), `InvoiceId` and `PackageId` are all missing. Provide at least one of them.
Error	No invoice found with invoice id: {InvoiceId} or invoice number: {InvoiceNumber}	`InvoiceId` was given but does not exist, and `InvoiceNumber` does not resolve to an existing invoice.
Error	No invoice package found with package Id: {PackageId}	The given `PackageId` does not exist in `pixi.InvoicePackage`.
Error	Two different invoices found with provided parameters InvoiceId: {InvoiceId} and InvoiceNumber: {InvoiceNumber}	`InvoiceId` and `InvoiceNumber` point to different invoices. This also happens if `InvoiceId` does not exist while `InvoiceNumber` is valid. Pass only one of them or consistent values.
Error	PackageId: {PackageId} does not belong to invoice with InvoiceId: {InvoiceId} or InvoiceNumber: {InvoiceNumber}	The given package belongs to a different invoice than the one given by `InvoiceId`/`InvoiceNumber`.
Info	No records found with provided parameters	The checks passed, but no package matches, e.g. the invoice has no packages or the invoice number does not exist.

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:pixiGetInvoicePackage>
      <!-- <InvoiceNumber>RE2024-001234</InvoiceNumber> -->
      <!-- <InvoiceId>98765</InvoiceId> -->
      <!-- <PackageId>4321</PackageId> -->
    </ns1:pixiGetInvoicePackage>
  </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:pixiGetInvoicePackage>
      <!-- <InvoiceNumber>RE2024-001234</InvoiceNumber> -->
      <!-- <InvoiceId>98765</InvoiceId> -->
      <!-- <PackageId>4321</PackageId> -->
    </ns1:pixiGetInvoicePackage>
  </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 = [
    // 'InvoiceNumber' => 'RE2024-001234',
    // 'InvoiceId' => '98765',
    // 'PackageId' => '4321',
];

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

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