pixiCreateBanklineMatch · Pixi API documentation

Creates a manual entry in BankMatch that links a bank line (BanklineKey) to an order.

Either OrderNr or OrderNrExternal must be passed, otherwise an error row is returned.
The order is looked up in OrderHeader with OrderNr = @OrderNr OR OrderNrExternal = @OrderNrExternal. The open amount is the order total, rounded to the number of decimal places from the setting NumberOfDecimalPlacesForPrices (default 2), minus PaidByCustomer.
The match difference is calculated as the absolute value of the remaining bank amount (BankAmount - UsedAmount) minus the open amount. If MaxMatchDelta is set and this difference is larger, nothing is written and an error row is returned.
If a match between this order and this bank line already exists, an error row is returned.
Otherwise a row is inserted into BankMatch with ManualMatch = 1, the current date and AmountMatched = the smaller of the remaining bank amount and the open amount.
If AutoReleaseOrder = 1, the difference between OrderTotal and PaidByCustomer of the order is checked again. If it is less than or equal to MaxMatchDelta (or 0 if not set), the order lines with status HAL are set to ANG (order released from hold). Otherwise the newly created match is deleted again.

The call always returns exactly one row with Status, Message and the current values of the bank line.

Notes

Status does not reveal the auto-release outcome: after the insert, Status is always OK and Message is always empty, even when the match was deleted again because the order could not be released. Check the order or BankMatch afterwards if this matters.
The auto-release check relies on PaidByCustomer having been updated after the insert. The code itself does not update it; this presumably happens via logic outside this procedure (e.g. a trigger), which is not visible here. If PaidByCustomer is NULL, the order is never released and the match is removed.
If both OrderNr and OrderNrExternal are passed, the OR filter may match several orders; then one of them is taken arbitrarily.
The existence of the bank line is not checked. For a non-existing BanklineKey no match is inserted, but Status is still OK. In this case the match key is taken from IDENT_CURRENT('BankMatch'), which is not session-scoped; together with AutoReleaseOrder = 1 and a failed release check this can delete an unrelated BankMatch row. The same risk exists under concurrent inserts.
If UsedAmount is NULL, AmountMatched becomes NULL (no ISNULL in the insert), while the delta check treats it as 0.
Reads use NOLOCK. The work runs in one transaction that is committed in all branches after the order lookup.
Errors in the release step (GOS_ReleaseOnHold) are logged to LogTable and re-raised; they reach the caller as SqlMessage.
Released order lines get UpdateEmp = BanklineMatch - API (payments), truncated to 20 characters.

Tables used

OrderHeader · Read BankLines · Read BankMatch · Write Numbers · Read Settings · Read Orderlines · Write LogTable · Write

Parameter	Type	Default	Description
`BanklineKey` Required	int	–	Key of the bank line (`BankLines.BankLineKey`) to be matched. Example: `4711`
`OrderNr`	int	NULL	Pixi order number. Either this or `OrderNrExternal` must be supplied. Example: `100234`
`OrderNrExternal`	varchar(50) string	NULL	External order number (e.g. shop order number). Used when `OrderNr` is not supplied. Example: `SHOP-2024-005871`
`MaxMatchDelta`	money decimal	NULL	Maximum allowed difference between the remaining bank amount and the open order amount. If NULL, no check is done before matching; for the auto-release check NULL counts as 0. Example: `0.05`
`AutoReleaseOrder`	bit boolean	0	If 1, the order is released from hold after matching when the remaining difference is within `MaxMatchDelta`; otherwise the new match is removed again. Allowed values `0` – Only create the match. `1` – Create the match and try to release the order (order lines `HAL` → `ANG`); remove the match if the order is not fully paid within the delta. Example: `1`

Result set 1 · Always (exactly one row).

Status row with the current values of the bank line. Bank line columns are NULL if the bank line does not exist.

Column	Type	Description
`Status`	varchar(5) string	`OK` on success, `ERROR` if a check failed.
`Message`	varchar(500) string	Error text; empty string on success.
`BankLineKey` Nullable	int	Key of the bank line.
`BankAmount` Nullable	decimal	Amount of the bank line.
`UsedAmount` Nullable	decimal	Amount of the bank line already used for matches, as currently stored.

Response example

<SqlRowSet1>
  <row>
    <Status>OK</Status>
    <Message/>
    <BankLineKey>4711</BankLineKey>
    <BankAmount>119.9000</BankAmount>
    <UsedAmount>0.0000</UsedAmount>
  </row>
</SqlRowSet1>

Status	Message	Cause
ERROR	OrderNr or OrderNrExternal must be supplied	Neither `OrderNr` nor `OrderNrExternal` was passed. Supply one of them.
ERROR	Order was not found	No order in `OrderHeader` matches the given order number. Check `OrderNr`/`OrderNrExternal`.
ERROR	The match difference is higher that the defined MaxMatchDelta	The difference between the remaining bank amount and the open order amount exceeds `MaxMatchDelta`. Increase the tolerance or match manually.
ERROR	Bankline match already exists	This bank line is already matched to this order in `BankMatch`.
RAISERROR	%s	An error occurred while releasing the order (`GOS_ReleaseOnHold`); the original SQL error message is logged to `LogTable` and re-raised.

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:pixiCreateBanklineMatch>
      <BanklineKey>4711</BanklineKey>
      <!-- <OrderNr>100234</OrderNr> -->
      <!-- <OrderNrExternal>SHOP-2024-005871</OrderNrExternal> -->
      <!-- <MaxMatchDelta>0.05</MaxMatchDelta> -->
      <!-- <AutoReleaseOrder>1</AutoReleaseOrder> -->
    </ns1:pixiCreateBanklineMatch>
  </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:pixiCreateBanklineMatch>
      <BanklineKey>4711</BanklineKey>
      <!-- <OrderNr>100234</OrderNr> -->
      <!-- <OrderNrExternal>SHOP-2024-005871</OrderNrExternal> -->
      <!-- <MaxMatchDelta>0.05</MaxMatchDelta> -->
      <!-- <AutoReleaseOrder>1</AutoReleaseOrder> -->
    </ns1:pixiCreateBanklineMatch>
  </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 = [
    'BanklineKey' => '4711',
    // 'OrderNr' => '100234',
    // 'OrderNrExternal' => 'SHOP-2024-005871',
    // 'MaxMatchDelta' => '0.05',
    // 'AutoReleaseOrder' => '1',
];

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

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