pixiCACreateManualBooking · Pixi API documentation

Adds a manual booking (for example a manual payment or a correction) to the customer account of the customer CustKey.

Steps:

EventDate defaults to the current date and time if it is not passed.
If MatchToInvoiceNr is set, the call looks up the newest customer account entry (MAX(CustomerAccountKey)) that refers to this invoice. The invoice must belong to CustKey. The key found replaces any value passed in MatchKey. If no entry is found, an error is returned.
EventID must exist in the customer account event definitions and must be flagged as manual (IsManual = 1).
EventDate must not be in the future.
If CurrencyId is not passed, the base currency of the shop the customer belongs to is used.
The booking is inserted with the user name API. The exchange rate is determined automatically for the shop, currency and EventDate.
If a match key is known (from MatchToInvoiceNr or MatchKey), the new entry is matched with that entry. The match is only created if both entries still have an open amount, the signs of the two entries are opposite, Amount is not 0 and the amount of the target entry is not 0. The matched amount is the smaller of the two open amounts.

The whole call runs in one transaction. It returns a single row with ReturnCode = OK on success or ERROR with the error text.

Notes

Validation errors and errors from the exchange rate lookup roll back the transaction and return an ERROR row.
Errors during the insert or the match inside the internal booking procedure are caught there and not passed on. In that case the call can still return OK although no booking was created. Check the customer account afterwards if this matters.
The customer account entry for the new booking is read back via ManualBookingRef. It is probably created by logic on the manual booking table that is not visible here.
The exchange rate lookup (pixi.GetExchRateID) and the match procedure (Pixi_CA_InsertMatch) are not attached; their exact behaviour is unknown.
MatchKey is not checked for belonging to the customer. Prefer MatchToInvoiceNr, which is checked.
CustKey is not validated explicitly. For an unknown customer, CurrencyId stays NULL if it is not passed.
The error text for a future date mentions a "paid date"; it refers to EventDate.
Lookups use NOLOCK.

Tables used

CustomerAccount · Read Invoices · Read CustomerAccountEvents · Read Shops · Read Customers · Read CustomerAccountManualBookings · Write

Parameter	Type	Default	Description
`CustKey` Required	int	–	Key of the customer whose account receives the booking. Example: `10234`
`EventID` Required	varchar(3) string	–	ID of the customer account event to book. The event must exist and be flagged as manual. Example: `MPY`
`Amount` Required	money decimal	–	Amount of the booking. Example: `49.90`
`EventDate`	datetime dateTime	NULL	Date and time of the booking. Must not be in the future. If `NULL`, the current date and time is used. Example: `2024-03-15T10:30:00`
`Comment`	varchar(512) string	NULL	Comment stored as reference of the booking. `NULL` is stored as an empty string. Example: `Bank transfer received 15.03.`
`MatchToInvoiceNr`	varchar(20) string	NULL	Number of an invoice of this customer. The new booking is matched with the newest account entry of this invoice. Overrides `MatchKey`. Example: `RE2024001234`
`MatchKey`	int	NULL	Key of the customer account entry (`CustomerAccountKey`) to match the new booking with. Ignored if `MatchToInvoiceNr` is set. Example: `558812`
`CurrencyId`	smallint int	NULL	Currency of the booking. If `NULL`, the base currency of the customer's shop is used. Example: `1`

Result set 1 · If a validation or processing error occurs (transaction is rolled back)

Error row.

Column	Type	Description
`ReturnCode`	varchar(5) string	Always `ERROR`.
`ErrorMessage` Nullable	nvarchar(4000) string	Text of the error.

Result set 2 · On success (transaction committed)

Success row.

Column	Type	Description
`ReturnCode`	varchar(2) string	Always `OK`.
`ErrorMessage`	varchar(44) string	Fixed text `Event successfully added to customer account`.

Response example

<SqlRowSet1>
  <row>
    <ReturnCode>OK</ReturnCode>
    <ErrorMessage>Event successfully added to customer account</ErrorMessage>
  </row>
</SqlRowSet1>

Status	Message	Cause
ERROR	Invoice {MatchToInvoiceNr} does not exist or does not belong to this customer	`MatchToInvoiceNr` was passed, but no customer account entry exists for an invoice with this number that belongs to `CustKey`.
ERROR	Parameter @EventID is mandatory	`EventID` was passed as `NULL`.
ERROR	Event {EventID} either does not exist or is not manual	The event ID is unknown or the event is not flagged as manual. Use an event with `IsManual = 1`.
ERROR	Paid date is set into the future	`EventDate` is later than the current date and time.

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:pixiCACreateManualBooking>
      <CustKey>10234</CustKey>
      <EventID>MPY</EventID>
      <Amount>49.90</Amount>
      <!-- <EventDate>2024-03-15T10:30:00</EventDate> -->
      <!-- <Comment>Bank transfer received 15.03.</Comment> -->
      <!-- <MatchToInvoiceNr>RE2024001234</MatchToInvoiceNr> -->
      <!-- <MatchKey>558812</MatchKey> -->
      <!-- <CurrencyId>1</CurrencyId> -->
    </ns1:pixiCACreateManualBooking>
  </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:pixiCACreateManualBooking>
      <CustKey>10234</CustKey>
      <EventID>MPY</EventID>
      <Amount>49.90</Amount>
      <!-- <EventDate>2024-03-15T10:30:00</EventDate> -->
      <!-- <Comment>Bank transfer received 15.03.</Comment> -->
      <!-- <MatchToInvoiceNr>RE2024001234</MatchToInvoiceNr> -->
      <!-- <MatchKey>558812</MatchKey> -->
      <!-- <CurrencyId>1</CurrencyId> -->
    </ns1:pixiCACreateManualBooking>
  </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 = [
    'CustKey' => '10234',
    'EventID' => 'MPY',
    'Amount' => '49.90',
    // 'EventDate' => '2024-03-15T10:30:00',
    // 'Comment' => 'Bank transfer received 15.03.',
    // 'MatchToInvoiceNr' => 'RE2024001234',
    // 'MatchKey' => '558812',
    // 'CurrencyId' => '1',
];

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

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