Replacements Write

pixiCreateReplacement

Creates a replacement order with negative quantities for selected order lines, based on the customer and addresses of an existing order.

Creates a new replacement order and returns the key of the new order header. The work is done by the internal procedure Pixi_CreateReplacementOrder.

Reads one order line of the order OrderNr (TOP 1 without sort order). Customer, invoice address, shipping address, LocationID and LastOrdLocationID are taken from it. The current date is used as creation date.
Copies the invoice address of that order line as a new record in Addresses. The Username is stored as creator and editor. All other fields are copied unchanged.
Reads the shipping country, the VAT liability (AddrNoChargeVAT) and the shop of the customer (CustomerOf) from the shipping address.
Parses Orderlines. Entries are separated by commas. Each entry has the form OrderlineKey;Quantity. The quantity is optional; without it the full quantity of the original line is used.
Reads the order type (default B2C), shipping costs, tax rates, VAT settings for shipping costs, currency and Address_Remarks from the order header of one of the listed order lines. It also looks up the invoice of that line in Invlines.
Determines an exchange rate for the currency and the current date and creates a new order header (Pixi_OrderHeader_Insert). The order uses the default CCP merchant from setting DefaultCCPMerchant and a discount of 0. The external order number is P + the new order number.
Inserts one order line per listed original line:
- quantity negated (-Quantity or -Qty), status MIN;
- prices, article data, serial number, Charge and best-before date copied;
- LocationID taken from the order OrderNr;
- tax rate recalculated from the order type, the VAT liability, the shipping country and the item's VAT class;
- line amounts negated and rounded: gross to 2 decimals for B2C (else 4), net to 2 decimals for B2B (else 4);
- amount differences negated.
Links the new order to the original invoice with a pixi.InvoiceAttribute record (TypeId 3, value = new order number).
Returns the new OrderHeaderKey and commits the transaction.

Notes

All work runs in one transaction. If an error occurs, the CATCH block only rolls back. No error message and no result row reach the caller. An empty response means that no replacement order was created.
The result row is sent before the commit. If the internal error counter is not 0, the transaction is rolled back although a key has already been returned.
@Orderlines is passed to a varchar(8000) parameter of the internal procedure. Longer lists are truncated.
The listed order lines are matched only by OrderlineKey. The code does not check that they belong to OrderNr. Customer and addresses come from OrderNr; order type, tax rates, currency and the linked invoice come from one of the listed lines. Pass only lines of the same order.
Which line of OrderNr is used for customer and addresses is not defined (TOP 1 without ORDER BY).
If a listed line has no invoice, the link record in pixi.InvoiceAttribute is written with an empty InvoiceId, or the insert fails depending on table constraints. A failure rolls back the whole call.
Order lines are only created for items that exist in items.
Reads use NOLOCK. CONTEXT_INFO is set to 0x10136 while the order lines are inserted, presumably to control triggers.
Pixi_OrderHeader_Insert, pixi.GetExchRateID, fpixi_GetSetting, fPixi_GetCommaSplit and fPixi_GetVATRate are not attached. Their exact behaviour, including how the order header is written, is not documented here.

Parameters

Parameter	Type	Default	Description
`OrderNr` Required	int	–	Number of the existing order. Customer, invoice address, shipping address and `LocationID` are taken from it. Example: `104512`
`Orderlines` Required	varchar(max) string	–	Comma-separated list of original order lines in the form `OrderlineKey;Quantity`. The quantity is optional; without it the full quantity of the line is used. The quantity is stored as a negative value. Effectively limited to 8000 characters. Example: `556781;1,556782;2`
`Username`	varchar(50) string	API	User name stored as creator and editor of the new address and order lines. Example: `API`

Response

Result set 1 · If no error occurs during processing. If an error occurs, nothing is returned.

Key of the newly created order header.

Column	Type	Description
`OrderHeaderKey`	int	`OrderHeaderKey` of the new replacement order; 0 if the header could not be found.

Response example

<SqlRowSet1>
  <row>
    <OrderHeaderKey>98765</OrderHeaderKey>
  </row>
</SqlRowSet1>

Examples

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:pixiCreateReplacement>
      <OrderNr>104512</OrderNr>
      <Orderlines>556781;1,556782;2</Orderlines>
      <!-- <Username>API</Username> -->
    </ns1:pixiCreateReplacement>
  </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:pixiCreateReplacement>
      <OrderNr>104512</OrderNr>
      <Orderlines>556781;1,556782;2</Orderlines>
      <!-- <Username>API</Username> -->
    </ns1:pixiCreateReplacement>
  </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 = [
    'OrderNr' => '104512',
    'Orderlines' => '556781;1,556782;2',
    // 'Username' => 'API',
];

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

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

Tables used

Orderlines · Write Addresses · Write Customers · Read OrderHeader · Write Invlines · Read items · Read Currency · Read InvoiceAttribute · Write

SQL object:: dbo.pipiCreateReplacement