pixiDFGetChangesConfirmation · Pixi API documentation

Acknowledges an order history entry from the Direct Fulfillment API. A supplier calls this after it has processed a change, so that the change is marked as delivered.

Authentication: The supplier is looked up in Suppliers by SupplNr, with CustNr = Secret, not disabled (Disabled <> 1) and enabled for direct fulfillment (CanDoDirectFulfillment = 1).
- If no supplier matches and the setting DFAPIAllowFullAccessWithoutSecret is 0, the call returns status 403. The setting is also treated as 0 if it does not exist.
- If the setting has any other value, the secret check is skipped.
Lookup: If the OrderHistKey does not exist in OrderHistory, the call returns status 404.
Update: Otherwise the internal procedure GOSUpdateOHClientNotifiedXML is executed:
- The order history entry gets ClientNotified = Y (only if OrderHistKey <> 0).
- If InvoiceKey <> 0, Invoices.TrackingIDSent of that Rechnung is set to the current date and time.
- On success the status is 200. If an error occurs, the status is 500 with the SQL error message.

The call always returns exactly one row with Status and ErrorMsg.

Notes

The code does not check that the OrderHistKey or the InvoiceKey belongs to the authenticated supplier. Any existing order history entry can be confirmed.
InvoiceKey is not validated. If the Rechnung does not exist, no row is updated, but the status is still 200.
The two updates are not wrapped in an explicit transaction. If the invoice update fails, the ClientNotified flag may already be set while the call returns 500.
The supplier lookup and the existence check use NOLOCK.
If OrderHistKey is NULL, the 404 message becomes NULL because of the string concatenation.

Tables used

Suppliers · Read Settings · Read OrderHistory · Write Invoices · Write

Parameter	Type	Default	Description
`SupplNr` Required	varchar(4) string	–	Supplier number of the direct fulfillment supplier. Example: `L001`
`Secret` Required	varchar(20) string	–	Secret of the supplier. It is compared with the `CustNr` field of the supplier. Example: `K12345`
`OrderHistKey` Required	int	–	Key of the order history entry to confirm. The entry is marked with `ClientNotified` = `Y`. Example: `584213`
`InvoiceKey`	int	0	Optional invoice key. If not 0, `TrackingIDSent` of this Rechnung is set to the current date and time. Example: `0`

Result set 1 · Always

One status row with the result of the confirmation.

Column	Type	Description
`Status`	varchar(3) string	HTTP-like status code: `200` success, `403` not authorized, `404` order history entry not found, `500` error during update.
`ErrorMsg` Nullable	varchar(2000) string	Message text: confirmation of success or the error description.

Response example

<SqlRowSet1>
  <row>
    <Status>200</Status>
    <ErrorMsg>ClientNotified flag successfully set for OrderHistKey(584213).</ErrorMsg>
  </row>
</SqlRowSet1>

Status	Message	Cause
403	Not Authorized. Secret or SupplNr is incorrect.	No active supplier with direct fulfillment matches `SupplNr` and `Secret`, and the setting `DFAPIAllowFullAccessWithoutSecret` is `0` or missing. Check the supplier number, the secret (`CustNr`), the `Disabled` flag and `CanDoDirectFulfillment`.
404	OrderHistKey({value}) not found.	No entry with the given `OrderHistKey` exists in `OrderHistory`. Use a key returned by the change feed.
500	{ERROR_MESSAGE()}	A SQL error occurred while updating `OrderHistory` or `Invoices`. The message contains the original SQL error text.

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:pixiDFGetChangesConfirmation>
      <SupplNr>L001</SupplNr>
      <Secret>K12345</Secret>
      <OrderHistKey>584213</OrderHistKey>
      <!-- <InvoiceKey>0</InvoiceKey> -->
    </ns1:pixiDFGetChangesConfirmation>
  </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:pixiDFGetChangesConfirmation>
      <SupplNr>L001</SupplNr>
      <Secret>K12345</Secret>
      <OrderHistKey>584213</OrderHistKey>
      <!-- <InvoiceKey>0</InvoiceKey> -->
    </ns1:pixiDFGetChangesConfirmation>
  </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 = [
    'SupplNr' => 'L001',
    'Secret' => 'K12345',
    'OrderHistKey' => '584213',
    // 'InvoiceKey' => '0',
];

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

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