pixiSupplierOrderChangeStatus · Pixi API documentation

Sets a new status (ChangeStatusIdTo) on supplier orders.

User resolution: if UserId is not given, the user ID is looked up from UserName in UCS_USERS. If the name does not exist, the ID of the user pixiAdministration is used.
Order selection: the orders are identified by one of these parameters:
- SupplierOrderId: a single supplier order ID. The value 0 is treated like NULL.
- SupplierOrderIds: a list of supplier order IDs, passed on unchanged to the internal procedure.
- SupplierOrderNR: used only if SupplierOrderId and SupplierOrderIds are both empty. The call looks up the supplier order with this InternalNumber. If several orders match, the one with the highest Id is used.
- If none of the three is given, the call returns Invalid parameters.
Status check: if ChangeStatusIdTo = 3 (confirmed, CON), the single order in SupplierOrderId must have status 2 (ordered, BES). Otherwise an error row is returned.
Status change: the call runs pixi.SupplierOrderChangeStatus through sp_executesql. It passes the user ID, the target status, the single ID and the ID list.
The call returns one row with ReturnCode = Success. If an error occurs, the row contains ERROR and the error message.

Notes

The actual status change is done by pixi.SupplierOrderChangeStatus, whose definition is not attached. Its exact logic, the tables it writes, the valid target status IDs, the expected format of SupplierOrderIds (probably comma-separated) and any result sets of its own are therefore unknown.
The CON/BES check only applies to SupplierOrderId, including the ID found via SupplierOrderNR. Orders passed only in SupplierOrderIds are not checked here.
If SupplierOrderNR matches no order, no error is returned. The call goes on with an empty ID.
The status check reads SupplierOrder with NOLOCK.
The call runs in its own transaction. If the caller already has an open transaction, a savepoint is used instead. On error the call rolls back to this point. A transaction that is no longer committable can cause a further error at this rollback.
AppName is declared but not used.
UserName has no default and must always be sent, even if UserId is given.

Tables used

SupplierOrder · Read UCS_USERS · Read

Parameter	Type	Default	Description
`AppName` Required	varchar(255) string	–	Name of the calling application. Not used by the code. Example: `MyWarehouseTool`
`UserId`	int	NULL	ID of the user who performs the change. If `NULL`, the ID is looked up from `UserName`. Example: `12`
`UserName` Required	varchar(50) string	–	User name used to look up the user ID when `UserId` is empty. If the name is unknown, the user `pixiAdministration` is used. Example: `jdoe`
`ChangeStatusIdTo` Required	int	–	ID of the target status. `3` (confirmed, CON) is only allowed if the order has status `2` (ordered, BES). Further valid values are defined in `pixi.SupplierOrderChangeStatus`. Example: `3`
`SupplierOrderId`	int	NULL	ID of a single supplier order. `0` is treated as `NULL`. Example: `4711`
`SupplierOrderIds`	varchar(8000) string	–	List of supplier order IDs for a bulk change, passed unchanged to `pixi.SupplierOrderChangeStatus`. The format is defined there, probably comma-separated. Example: `4711,4712,4713`
`SupplierOrderNR`	int	NULL	Internal number (`InternalNumber`) of a supplier order. Only used if `SupplierOrderId` and `SupplierOrderIds` are empty. If several orders match, the one with the highest `Id` is used. Example: `100234`

Result set 1 · Always, exactly one status row (success or error)

Status row of the call.

Column	Type	Description
`ReturnCode`	varchar(7) string	`Success` or `ERROR`.
`ErrorMessage` Nullable	nvarchar(4000) string	Error text. `NULL` on success.

Response example

<SqlRowSet1>
  <row>
    <ReturnCode>Success</ReturnCode>
    <ErrorMessage/>
  </row>
</SqlRowSet1>

Status	Message	Cause
ERROR	Invalid parameters	None of `SupplierOrderId`, `SupplierOrderIds` and `SupplierOrderNR` was given. Send at least one of them.
ERROR	Status confirmed (CON) can only be set when order has status ordered (BES)	`ChangeStatusIdTo` = 3 was requested, but the supplier order does not have status 2 (ordered). Set the order to ordered first.
ERROR	{ERROR_MESSAGE()}	An SQL error occurred in `pixi.SupplierOrderChangeStatus`, for example an invalid status transition. The message is passed through and the changes are rolled back.

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:pixiSupplierOrderChangeStatus>
      <AppName>MyWarehouseTool</AppName>
      <!-- <UserId>12</UserId> -->
      <UserName>jdoe</UserName>
      <ChangeStatusIdTo>3</ChangeStatusIdTo>
      <!-- <SupplierOrderId>4711</SupplierOrderId> -->
      <!-- <SupplierOrderIds>4711,4712,4713</SupplierOrderIds> -->
      <!-- <SupplierOrderNR>100234</SupplierOrderNR> -->
    </ns1:pixiSupplierOrderChangeStatus>
  </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:pixiSupplierOrderChangeStatus>
      <AppName>MyWarehouseTool</AppName>
      <!-- <UserId>12</UserId> -->
      <UserName>jdoe</UserName>
      <ChangeStatusIdTo>3</ChangeStatusIdTo>
      <!-- <SupplierOrderId>4711</SupplierOrderId> -->
      <!-- <SupplierOrderIds>4711,4712,4713</SupplierOrderIds> -->
      <!-- <SupplierOrderNR>100234</SupplierOrderNR> -->
    </ns1:pixiSupplierOrderChangeStatus>
  </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 = [
    'AppName' => 'MyWarehouseTool',
    // 'UserId' => '12',
    'UserName' => 'jdoe',
    'ChangeStatusIdTo' => '3',
    // 'SupplierOrderId' => '4711',
    // 'SupplierOrderIds' => '4711,4712,4713',
    // 'SupplierOrderNR' => '100234',
];

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

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