pixiSupplierOrderLineCreate · Pixi API documentation

Adds lines to an existing purchase order (supplier order).

The user is resolved from UserName. If the name is unknown, the user pixiAdministration is used.
ConsiderPackageUnits and ConsiderMinOrderQty are set to 0 if NULL.
The purchase order is searched in SupplierOrder by Id = SupplierOrderId or InternalNumber = SupplierOrderNr. Exactly one order must match:
- no match: error Purchase order does not exist!
- more than one match: error Parameters @SupplierOrderId and @SupplierOrderNr belong to different purchase order!
The order must have status 1 (NEW) or 2 (BES). Otherwise the call returns Purchase order is not in status NEW or BES!
If all checks pass, the internal procedure pixi.SupplierOrderLineCreate creates the lines. It receives the order ID, the user ID, both flags and PurchaseOrderXML.

The call returns one result set with status rows (Status, StatusDescription, ItemId), sorted by Status and ItemId.

Notes

The actual line creation is done by pixi.SupplierOrderLineCreate, which is not attached. Several things therefore cannot be documented here:
- the expected structure of PurchaseOrderXML
- how package units and minimum order quantities are applied
- which tables are written
- which status and description values appear in the result on success
pixi.SupplierOrderLineCreate is called with @pipiSupplierOrderLineCreate_ReturnInfo = 1. Presumably it writes its per-item results into the temporary result table that this call returns.
Pass only one of SupplierOrderId or SupplierOrderNr, or make sure both refer to the same order. The lookup uses OR, so two different matches cause an error. If both are NULL, nothing matches and Purchase order does not exist! is returned.
The order lookup uses NOLOCK.
The call runs in its own transaction, or in a savepoint if a transaction is already open.
On a SQL error the transaction is rolled back and the error is logged via log.InsertError. Whether the error is passed on to the caller depends on that procedure, which is not attached. In that case the status result set may be missing.

Tables used

SupplierOrder · Read UCS_USERS · Read

Parameter	Type	Default	Description
`SupplierOrderId`	int	NULL	Internal ID of the purchase order (`SupplierOrder.Id`). Alternative to `SupplierOrderNr`. Example: `1542`
`SupplierOrderNr`	int	NULL	Internal number of the purchase order (`SupplierOrder.InternalNumber`). Alternative to `SupplierOrderId`. Example: `20231`
`UserName`	varchar(50) string	–	Pixi user name under which the lines are created. Falls back to `pixiAdministration` if the name is unknown. Example: `jdoe`
`ConsiderPackageUnits`	bit boolean	0	Whether package units are considered when creating the lines. `NULL` is treated as `0`. Allowed values `0` – Do not consider package units `1` – Consider package units Example: `1`
`ConsiderMinOrderQty`	bit boolean	0	Whether the minimum order quantity is considered when creating the lines. `NULL` is treated as `0`. Allowed values `0` – Do not consider minimum order quantity `1` – Consider minimum order quantity Example: `0`
`PurchaseOrderXML` Required	xml	–	XML document with the lines to add. It is passed unchanged to `pixi.SupplierOrderLineCreate`. Its structure is defined there and is not visible in this code, so the example is only illustrative. Example: `<PurchaseOrder> <Items> <Item> <ItemId>4711</ItemId> <Quantity>10</Quantity> </Item> </Items> </PurchaseOrder>`

Result set 1 · Always, unless a SQL error occurs

Status rows from validation or from the line creation, sorted by Status and ItemId.

Column	Type	Description
`Status` Nullable	varchar(120) string	Status of the row, e.g. `Error`. Other values are set by `pixi.SupplierOrderLineCreate`.
`StatusDescription` Nullable	varchar(120) string	Text describing the status.
`ItemId` Nullable	int	Item the row refers to. `NULL` for order-level errors.

Response example

<SqlRowSet1>
  <row>
    <Status>Error</Status>
    <StatusDescription>Purchase order is not in status NEW or BES!</StatusDescription>
  </row>
</SqlRowSet1>

Status	Message	Cause
Error	Purchase order does not exist!	No purchase order matches `SupplierOrderId` or `SupplierOrderNr`, or both are empty. Pass a valid ID or number.
Error	Parameters @SupplierOrderId and @SupplierOrderNr belong to different purchase order!	The lookup found more than one order, for example because ID and number refer to different orders. Pass only one identifier or matching values.
Error	Purchase order is not in status NEW or BES!	The purchase order has a status other than 1 (NEW) or 2 (BES). Lines can only be added to orders in these statuses.

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:pixiSupplierOrderLineCreate>
      <!-- <SupplierOrderId>1542</SupplierOrderId> -->
      <!-- <SupplierOrderNr>20231</SupplierOrderNr> -->
      <!-- <UserName>jdoe</UserName> -->
      <!-- <ConsiderPackageUnits>1</ConsiderPackageUnits> -->
      <!-- <ConsiderMinOrderQty>0</ConsiderMinOrderQty> -->
      <PurchaseOrderXML><![CDATA[<PurchaseOrder><Items><Item><ItemId>4711</ItemId><Quantity>10</Quantity></Item></Items></PurchaseOrder>]]></PurchaseOrderXML>
    </ns1:pixiSupplierOrderLineCreate>
  </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:pixiSupplierOrderLineCreate>
      <!-- <SupplierOrderId>1542</SupplierOrderId> -->
      <!-- <SupplierOrderNr>20231</SupplierOrderNr> -->
      <!-- <UserName>jdoe</UserName> -->
      <!-- <ConsiderPackageUnits>1</ConsiderPackageUnits> -->
      <!-- <ConsiderMinOrderQty>0</ConsiderMinOrderQty> -->
      <PurchaseOrderXML><![CDATA[<PurchaseOrder><Items><Item><ItemId>4711</ItemId><Quantity>10</Quantity></Item></Items></PurchaseOrder>]]></PurchaseOrderXML>
    </ns1:pixiSupplierOrderLineCreate>
  </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 = [
    // 'SupplierOrderId' => '1542',
    // 'SupplierOrderNr' => '20231',
    // 'UserName' => 'jdoe',
    // 'ConsiderPackageUnits' => '1',
    // 'ConsiderMinOrderQty' => '0',
    'PurchaseOrderXML' => '<PurchaseOrder><Items><Item><ItemId>4711</ItemId><Quantity>10</Quantity></Item></Items></PurchaseOrder>',
];

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

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