pixiCAInsertMatch

Links two customer account entries, for example a payment and an invoice, with a match amount.

The call first runs the common API envelope. This checks the call frequency limit for pipiCAInsertMatch and records the time of the call. If the limit is exceeded, a row with ResultCode 502 and ResultText is returned and nothing else happens.
If CAref1, CAref2 or MatchAmount is NULL, a status row with ReturnCode = ERROR and ErrorMessage is returned. No data is written.
Otherwise one record is inserted into CustomerAccountMatch:
- CAref1 and CAref2 are stored as passed.
- AbsoluteMatchAmount is set to MatchAmount rounded to 2 decimal places.
- Creation and update user are set to API, with the current date and time.

On success the call returns no result set.

Notes

The insert runs in its own transaction, or in a savepoint if a transaction is already open.
SQL errors during the insert are caught, rolled back and logged via log.InsertError, which is not attached. Examples are constraint violations for non-existing CAref values. The caller receives no error row in this case, so success cannot be told apart from a failed insert by the response alone.
The code does not check whether CAref1 and CAref2 exist, whether they belong to the same customer, or whether the amount matches the open balances. Any such checks depend on table constraints that are not visible here.
The ID of the new match record is only used as the internal procedure return value and is not returned to the SOAP caller.
CAref1, CAref2 and MatchAmount have no default. Leaving them out of the request causes a SQL error for the missing parameter. The ERROR row only appears if they are passed explicitly as NULL.
The error text contains a typo: it names CAref1 twice instead of CAref1 and CAref2.
Frequency limits are configured in API_CONTROL (MIN_BREATHING_MSEC).

Tables used

API_STATISTICS · Write API_CONTROL · Read CustomerAccountMatch · Write

Parameter	Type	Default	Description
`CAref1` Required	int	–	Key of the first customer account entry to be matched. Example: `15234`
`CAref2` Required	int	–	Key of the second customer account entry to be matched. Example: `15240`
`MatchAmount` Required	money decimal	–	Amount to be matched. It is rounded to 2 decimal places and stored as `AbsoluteMatchAmount`. Example: `49.90`
`ResultCode` OUTPUT	char(3) string	NULL	Output: result code of the API envelope, `200` if the call was allowed or `502` if the frequency limit was exceeded. Allowed values `200` – Call allowed (OK) `502` – Frequency limit exceeded
`ResultText` OUTPUT	varchar(1024) string	NULL	Output: text belonging to `ResultCode`, either `OK` or the frequency limit message.

Result set 1 · Only if the call frequency limit for this function is exceeded

Throttling status row from the API envelope.

Column	Type	Description
`ResultCode`	char(3) string	Always `502` in this case.
`ResultText`	varchar(1024) string	Message with the remaining wait time in milliseconds.

Result set 2 · If `CAref1`, `CAref2` or `MatchAmount` is NULL

Validation error row.

Column	Type	Description
`ReturnCode`	varchar(5) string	Always `ERROR`.
`ErrorMessage`	varchar(46) string	Error text.

Response example

<SqlRowSet1>
  <row>
    <ReturnCode>ERROR</ReturnCode>
    <ErrorMessage>CAref1, CAref1 and MatchAmount cannot be NULL</ErrorMessage>
  </row>
</SqlRowSet1>

Status	Message	Cause
ERROR	CAref1, CAref1 and MatchAmount cannot be NULL	`CAref1`, `CAref2` or `MatchAmount` was passed as NULL. Pass all three values.
502	({value}) Frequency quote exceeded. Next call to this function can be made in ca. {value} milliseconds	The function was called again before the minimum interval configured in `API_CONTROL` had passed. Wait the indicated time before retrying.

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:pixiCAInsertMatch>
      <CAref1>15234</CAref1>
      <CAref2>15240</CAref2>
      <MatchAmount>49.90</MatchAmount>
      <!-- <ResultCode>?</ResultCode> -->
      <!-- <ResultText>?</ResultText> -->
    </ns1:pixiCAInsertMatch>
  </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:pixiCAInsertMatch>
      <CAref1>15234</CAref1>
      <CAref2>15240</CAref2>
      <MatchAmount>49.90</MatchAmount>
      <!-- <ResultCode>?</ResultCode> -->
      <!-- <ResultText>?</ResultText> -->
    </ns1:pixiCAInsertMatch>
  </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 = [
    'CAref1' => '15234',
    'CAref2' => '15240',
    'MatchAmount' => '49.90',
    // 'ResultCode' => '?',
    // 'ResultText' => '?',
];

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

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

Notes

Tables used

Result set 1 · Only if the call frequency limit for this function is exceeded

Result set 2 · If CAref1, CAref2 or MatchAmount is NULL

Response example

Result set 2 · If `CAref1`, `CAref2` or `MatchAmount` is NULL