pixiShipoutInvoice

Performs a complete ship-out of one invoice via the API, identified by InvoiceNr, by BoxNr or by both.

Preparation and checks

BoxNr = 0 is treated as NULL. InvoiceNr, TrackingID and ShipVendorCode are trimmed; empty strings become NULL.
The setting Centralized_Ship_Out or Premium_API must be enabled.
At least one of InvoiceNr / BoxNr is required.
LocID must exist in Location; a given BoxNr must exist in boxes (at any location).
The invoice is searched by InvoiceNr on location LocID and, additionally, via the order lines contained in box BoxNr on that location. Only invoice lines whose order line status is not MIN are considered. The box is taken from the box items of these order lines.
If no invoice is found, No invoice found is returned. If more than one combination of invoice/box is found (e.g. the box holds lines of several invoices, or the invoice lines are spread over several boxes or are only partly boxed), or the found invoice/box differs from the given one, an error row is returned.

Ship-out

If the invoice has a RefToInvoiceKey, box number -2 is used (the subsequent scan-out then fails with 0004. NO BOX !!!). Otherwise an existing box at the location containing the invoice lines is used, or a new box is created for the invoice. If the customer or shipping address is locked or the invoice is already scanned out, a negative box number results and the scan-out fails as well.
The number of packages is set to AmountOfPackages (minimum 1); invoice packages are added or removed accordingly.
The shipping vendor is set to ShipVendorCode (or the invoice's current vendor if not given).
The box is scanned out: lock and payment checks, invoice scan-out, order lines set to status AUS, box emptied, picklist box entries removed, poll records created.
Only if the scan-out did not return ERROR:
- the weight is written to the invoice and its packages (only if setting CalculateWeightFromItems is not enabled; if Weight is not given, the current PackageGrossWeight of the invoice is used),
- TrackingID (semicolon-separated list) is stored on the invoice packages and the invoice,
- stock reserved on the picklist is released using the stock movement operation DirectInvoicesWizard of application ShippingClient_A (user Shipout (API)),
- for direct invoices (InvCreationMode = Direct) the box including its items is deleted.

The call returns exactly one row with Status and StatusMessage. On success Status is OK and StatusMessage is empty.

Notes

The call is not wrapped in one transaction. Package count and shipping vendor are updated before the scan-out and remain changed even if the scan-out returns ERROR. A box created for the invoice may also remain.
The parameter BoxNr is only used to find the invoice and to validate the combination; the box that is actually scanned out is determined internally (existing box with the invoice lines on LocID, or a newly created box).
Already scanned-out invoices, invoices with a RefToInvoiceKey and invoices of locked customers/addresses end with 0004. NO BOX !!! rather than a specific message.
The error Invoice ... could not be found on location ... is practically unreachable, because an empty result is already reported as No invoice found.
If LocID is passed as NULL, the invoice's own location is used; error messages that concatenate LocID would then be NULL.
Settings read at runtime: Centralized_Ship_Out, Premium_API, CalculateWeightFromItems; in called procedures also EnableMultiInvoiceShipOut, DoNotReleaseStockOnDirectInvoiceScanOut and setting 7 (default weight 0.1 if weight is 0).
The scan-out retries up to five times on deadlocks; other SQL errors are logged and raised (returned as SqlMessage).
Reads use NOLOCK; the scan-out locks the box row with UPDLOCK. Pakete are updated under the app lock PixiInvoicePackage (timeout 30 s).
Events InvoiceChanged may be published when tracking IDs are set.

pixiUpdateInvoicePackage

Tables used

Settings · Read Location · Read boxes · Read boxitems · Read Invoices · Read Invlines · Read Orderlines · Read

Parameter	Type	Default	Description
`InvoiceNr`	varchar(20) string	NULL	Number of the invoice to ship out. Either this or `BoxNr` must be provided. Example: `1000234`
`UserName`	varchar(50) string	API	User name recorded for box creation, scan-out and tracking ID update. Example: `API`
`LocID`	char(3) string	001	Location (warehouse) ID. Invoice and box are searched on this location. If NULL, the invoice's location is used. Example: `001`
`BoxNr`	int	NULL	Box number containing the invoice's order lines. 0 is treated as NULL. Either this or `InvoiceNr` must be provided. Example: `4711`
`Weight`	float decimal	NULL	Gross weight to store on the invoice and its packages. If NULL, the current `PackageGrossWeight` of the invoice is used. Ignored if setting `CalculateWeightFromItems` is enabled. Example: `2.35`
`AmountOfPackages`	int	1	Number of packages for the invoice. Values below 1 are treated as 1. Example: `1`
`ShipVendorCode`	varchar(3) string	NULL	Shipping vendor code to set on the invoice. If empty, the invoice's current vendor is kept. Example: `DHL`
`TrackingID`	varchar(8000) string	NULL	One or more tracking IDs, separated by semicolons. Stored only after a successful scan-out. Example: `00340434161094015902;00340434161094015903`

Result set 1 · Always; exactly one row (validation error row or result of the scan-out).

Status of the ship-out.

Column	Type	Description
`Status`	varchar(50) string	`OK` on success, otherwise `ERROR`.
`StatusMessage` Nullable	varchar(50) string	Empty on success, otherwise the error message (validation messages may be longer than 50 characters).

Response example

<SqlRowSet1>
  <row>
    <Status>OK</Status>
    <StatusMessage/>
  </row>
</SqlRowSet1>

Status	Message	Cause
ERROR	Setting "Centralized_Ship_Out" or "Premium_API" is not enabled.	Neither setting `Centralized_Ship_Out` nor `Premium_API` is enabled.
ERROR	At least one of parameters InvoiceNr/BoxNr needs to be provided.	Both `InvoiceNr` and `BoxNr` are empty (or `BoxNr` is 0).
ERROR	Location with location ID: {LocID} does not exist.	`LocID` is not a valid location ID.
ERROR	Box with box number: {BoxNr} does not exist.	The given `BoxNr` does not exist in any location.
ERROR	No invoice found	No invoice with relevant lines was found for `InvoiceNr` or `BoxNr` on the location.
ERROR	Invoice with invoice number: "{InvoiceNr}" or box with box number: "{BoxNr}" could not be found on location "{LocID}"	Nothing found on the location; practically unreachable because `No invoice found` is returned first.
ERROR	Invoice with invoice number: "{InvoiceNr}" does not belong to box with box number: "{BoxNr}	Invoice and box do not match, the box contains several invoices, or the invoice lines are in several boxes or only partly boxed.
ERROR	0001. No Invoice !!!	The box exists but is not waiting for send (`WaitForSend` is not `Y`).
ERROR	0002. SHIPPING LOCK !!!	The customer of the shipping address has a shipping lock.
ERROR	0003. ORDER SHIPPING LOCK !!!	The shipping address has a shipping lock.
ERROR	0004. NO BOX !!!	No box to scan out on the location, e.g. invoice already scanned out, invoice has a `RefToInvoiceKey`, or customer/address locked.
ERROR	DIE RECHNUNG IST NICHT BEZAHLT !!!	The payment method requires payment before ship-out (`CA_DoNotAllowShipOutIfNotPaid`) and the invoice has an open amount.
ERROR	0006. NO INVOICE !!!	The box contains no items that belong to an invoice.
ERROR	0007. SQL Exception on Ship Out	An SQL error (other than a deadlock within the retry limit) occurred during scan-out.
RAISERROR	ScanOUT Error --- {error message}	Raised by the scan-out together with `0007`; returned as `SqlMessage`.

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:pixiShipoutInvoice>
      <!-- <InvoiceNr>1000234</InvoiceNr> -->
      <!-- <UserName>API</UserName> -->
      <!-- <LocID>001</LocID> -->
      <!-- <BoxNr>4711</BoxNr> -->
      <!-- <Weight>2.35</Weight> -->
      <!-- <AmountOfPackages>1</AmountOfPackages> -->
      <!-- <ShipVendorCode>DHL</ShipVendorCode> -->
      <!-- <TrackingID>00340434161094015902;00340434161094015903</TrackingID> -->
    </ns1:pixiShipoutInvoice>
  </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:pixiShipoutInvoice>
      <!-- <InvoiceNr>1000234</InvoiceNr> -->
      <!-- <UserName>API</UserName> -->
      <!-- <LocID>001</LocID> -->
      <!-- <BoxNr>4711</BoxNr> -->
      <!-- <Weight>2.35</Weight> -->
      <!-- <AmountOfPackages>1</AmountOfPackages> -->
      <!-- <ShipVendorCode>DHL</ShipVendorCode> -->
      <!-- <TrackingID>00340434161094015902;00340434161094015903</TrackingID> -->
    </ns1:pixiShipoutInvoice>
  </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' => '1000234',
    // 'UserName' => 'API',
    // 'LocID' => '001',
    // 'BoxNr' => '4711',
    // 'Weight' => '2.35',
    // 'AmountOfPackages' => '1',
    // 'ShipVendorCode' => 'DHL',
    // 'TrackingID' => '00340434161094015902;00340434161094015903',
];

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

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

Notes

Related calls

Tables used

Result set 1 · Always; exactly one row (validation error row or result of the scan-out).

Response example