pixiSetInvoiceShippingInformation

Sets shipping information on a single invoice in table Invoices, identified by InvoiceNr.

The call checks whether an invoice with the given InvoiceNr exists. If not, it returns a status row with Status = 400 and nothing is changed.
It reads the current values of PackageNetWeight, PackageGrossWeight, Packages and ShipVendor.
It updates the invoice. Each field is only overwritten if the matching parameter is not NULL. Parameters that are left out or sent as NULL keep the current value. This allows partial updates, e.g. only the number of packages.
If at least one row was updated, it returns Status = 200 with the stored values of the invoice. Otherwise it returns Status = 500 with the current values.

Notes

A field cannot be reset to NULL with this call, because NULL parameters mean "keep current value".
ShipVendor is not validated. Any value of up to 3 characters is written as is.
Weights are not checked for plausibility, e.g. gross weight smaller than net weight or negative values.
The existence check and the reading of the old values use NOLOCK. No explicit transaction is used.
In practice the 500 branch only occurs if the invoice is deleted between the check and the update. In that case the row of the 500 result usually contains no data.
If several rows share the same InvoiceNr, all of them are updated and all are returned.
The column types in the result are taken from the variables declared in the code. The table definition of Invoices is not attached.

Tables used

Invoices · Write

Parameter	Type	Default	Description
`InvoiceNr`	varchar(20) string	NULL	Number of the invoice to update. Practically mandatory: without a matching invoice the call returns status `400`. Example: `RE2024001234`
`PackageNetWeight`	float decimal	NULL	New net weight of the package(s). `NULL` keeps the current value. Example: `2.35`
`PackageGrossWeight`	float decimal	NULL	New gross weight of the package(s). `NULL` keeps the current value. Example: `2.8`
`Packages`	int	NULL	New number of packages. `NULL` keeps the current value. Example: `2`
`ShipVendor`	varchar(3) string	NULL	New shipping vendor code, up to 3 characters. The value is not validated. `NULL` keeps the current value. Example: `DHL`

Result set 1 · If the invoice exists and at least one row was updated (`Status` = 200)

Success row with the stored shipping information of the invoice.

Column	Type	Description
`Status`	int	Always `200`.
`Message`	varchar(21) string	`Data updated in pixi*`
`InvoiceNr`	varchar(20) string	Invoice number.
`Packages` Nullable	int	Number of packages after the update.
`PackageNetWeight` Nullable	float decimal	Net weight after the update.
`PackageGrossWeight` Nullable	float decimal	Gross weight after the update.
`ShipVendor` Nullable	varchar(3) string	Shipping vendor code after the update.

Result set 2 · If the invoice existed but no row was updated (`Status` = 500)

Error row with the same columns as the success row, filled from the current invoice data, if it still exists.

Column	Type	Description
`Status`	int	Always `500`.
`Message`	varchar(35) string	`Data could not be updated in pixi*.`
`InvoiceNr`	varchar(20) string	Invoice number.
`Packages` Nullable	int	Current number of packages.
`PackageNetWeight` Nullable	float decimal	Current net weight.
`PackageGrossWeight` Nullable	float decimal	Current gross weight.
`ShipVendor` Nullable	varchar(3) string	Current shipping vendor code.

Result set 3 · If no invoice with `@InvoiceNr` exists (`Status` = 400)

Error row without invoice data.

Column	Type	Description
`Status`	int	Always `400`.
`Message`	varchar(38) string	`Invoice Nr could not be found in pixi*`

Response example

<SqlRowSet1>
  <row>
    <Status>200</Status>
    <Message>Data updated in pixi*</Message>
    <InvoiceNr>RE2024001234</InvoiceNr>
    <Packages>2</Packages>
    <PackageNetWeight>2.35</PackageNetWeight>
    <PackageGrossWeight>2.8</PackageGrossWeight>
    <ShipVendor>DHL</ShipVendor>
  </row>
</SqlRowSet1>

Status	Message	Cause
400	Invoice Nr could not be found in pixi*	No invoice with the given `InvoiceNr` exists, or `InvoiceNr` was not sent. Check the invoice number.
500	Data could not be updated in pixi*.	The update affected no row, e.g. because the invoice was deleted between the existence check and the update. Retry or check the 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:pixiSetInvoiceShippingInformation>
      <!-- <InvoiceNr>RE2024001234</InvoiceNr> -->
      <!-- <PackageNetWeight>2.35</PackageNetWeight> -->
      <!-- <PackageGrossWeight>2.8</PackageGrossWeight> -->
      <!-- <Packages>2</Packages> -->
      <!-- <ShipVendor>DHL</ShipVendor> -->
    </ns1:pixiSetInvoiceShippingInformation>
  </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:pixiSetInvoiceShippingInformation>
      <!-- <InvoiceNr>RE2024001234</InvoiceNr> -->
      <!-- <PackageNetWeight>2.35</PackageNetWeight> -->
      <!-- <PackageGrossWeight>2.8</PackageGrossWeight> -->
      <!-- <Packages>2</Packages> -->
      <!-- <ShipVendor>DHL</ShipVendor> -->
    </ns1:pixiSetInvoiceShippingInformation>
  </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',
    // 'PackageNetWeight' => '2.35',
    // 'PackageGrossWeight' => '2.8',
    // 'Packages' => '2',
    // 'ShipVendor' => 'DHL',
];

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

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

Notes

Tables used

Result set 1 · If the invoice exists and at least one row was updated (Status = 200)

Result set 2 · If the invoice existed but no row was updated (Status = 500)

Result set 3 · If no invoice with @InvoiceNr exists (Status = 400)

Response example

Result set 1 · If the invoice exists and at least one row was updated (`Status` = 200)

Result set 2 · If the invoice existed but no row was updated (`Status` = 500)

Result set 3 · If no invoice with `@InvoiceNr` exists (`Status` = 400)