pixiCreateReturnCase · Pixi API documentation

Inserts one new record into RET_CASES and returns the identifiers of the new return case.

The new record is filled as follows:

CreateDate: current server date and time.
CreateEmp: the value of Employee followed by (API). If Employee is NULL, the value API is used.
RETURN_DATE: the value of ReturnDate. If it is NULL, the current server date and time is used.
STATUS: always NEW.
RECEIVERS_COMMENT: the value of ReceiversComment.

After the insert, the call reads the new record by its identity value (SCOPE_IDENTITY()) and returns one row with RET_ID and RET_NUMBER.

Notes

All three parameters have no SQL default and must be sent in the request. NULL values are accepted: Employee and ReturnDate are replaced as described; ReceiversComment is stored as NULL.
The call only creates the return case header. No order, items or return lines are linked; this has to be done with other calls.
RET_NUMBER is not set by this procedure. It is presumably generated by the database (column default, computed column or trigger on RET_CASES), which is not visible in the code.
The suffix (API) adds 6 characters to Employee; whether the result fits into CreateEmp depends on the column length, which is not visible in the code.
The result row is read with NOLOCK. The insert and the select are not wrapped in an explicit transaction.

Tables used

RET_CASES · Write

Parameter	Type	Default	Description
`ReturnDate` Required	datetime dateTime	–	Date of the return. If NULL, the current server date and time is used. Example: `2024-05-14T10:30:00`
`ReceiversComment` Required	varchar(max) string	–	Comment of the receiver, stored in `RECEIVERS_COMMENT`. May be NULL. Example: `Package received damaged, customer requests refund.`
`Employee` Required	varchar(50) string	–	Employee short name. Stored as creator with the suffix `(API)`; if NULL, `API` is stored. Example: `JD`

Result set 1 · Always, after the insert succeeded

One row with the identifiers of the newly created return case.

Column	Type	Description
`RET_ID`	int	Internal ID (identity) of the new return case.
`RET_NUMBER` Nullable	string	Return number of the new return case, as generated by the database.

Response example

<SqlRowSet1>
  <row>
    <RET_ID>1523</RET_ID>
    <RET_NUMBER>R001523</RET_NUMBER>
  </row>
</SqlRowSet1>

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:pixiCreateReturnCase>
      <ReturnDate>2024-05-14T10:30:00</ReturnDate>
      <ReceiversComment>Package received damaged, customer requests refund.</ReceiversComment>
      <Employee>JD</Employee>
    </ns1:pixiCreateReturnCase>
  </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:pixiCreateReturnCase>
      <ReturnDate>2024-05-14T10:30:00</ReturnDate>
      <ReceiversComment>Package received damaged, customer requests refund.</ReceiversComment>
      <Employee>JD</Employee>
    </ns1:pixiCreateReturnCase>
  </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 = [
    'ReturnDate' => '2024-05-14T10:30:00',
    'ReceiversComment' => 'Package received damaged, customer requests refund.',
    'Employee' => 'JD',
];

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

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