pixiSetInvoicePaid · Pixi API documentation

Wrapper around the internal procedure pixi_SetInvoicePaid. It returns a status row with Status and Message.

Steps of the internal procedure:

Looks up the invoice in Invoices by InvoiceNR. It reads the customer, the total, the paid sum, the currency and the exchange rate.
Determines the customer account entry of the invoice with Pixi_CA_GetCustomerAccountforInvoice. The booking amount is the negated OpenToMatch of that entry.
Validates the input in this order:
- paid must be 1. Setting an invoice to unpaid is not supported.
- The invoice must exist.
- The invoice must not be fully paid already (total = PayedSum).
- eventID must be given.
- The event must exist in CustomerAccountEvents with IsManual = 1 and OriginalAmountMultiply = 1, i.e. a manual, positive event.
- PaidDate (default: current date and time) must not lie in the future.
Creates a manual booking event with Pixi_CA_InsertManualBookingEvent:
- The event uses the invoice's currency and exchange rate.
- The user name is API.
- The event is matched against the invoice's customer account entry.

On success the call returns Status = Success. If an error reaches the wrapper, it returns Status = Error with the error text.

Notes

PaidSum has no effect on the booked amount. A value of 0 is replaced by NULL, but the parameter is not used otherwise. The booking always covers the full open amount (OpenToMatch) of the invoice's customer account entry.
The internal procedure runs in its own transaction, or in a savepoint if a transaction is already open. XACT_ABORT is on, and the transaction is rolled back on error.
In its CATCH block the internal procedure calls log.InsertError with parameter 1. That object is not attached. Whether it re-raises the error is therefore unknown. Only if it does will the wrapper return the Error row; otherwise a failed call could still report Success.
The customer account lookup runs before the validation. For a non-existing invoice it is called with NULL keys.
Invoices and CustomerAccountEvents are read with NOLOCK.
The tables written by Pixi_CA_InsertManualBookingEvent are not visible in the attached code.
The 'already paid' check compares total and PayedSum for exact equality. A partially paid invoice is booked with its remaining open amount.

Tables used

Invoices · Read CustomerAccountEvents · Read

Parameter	Type	Default	Description
`InvoiceNR` Required	varchar(20) string	–	Number of the invoice to set to paid (`Invoices.InvoiceNr`). Example: `RE2024001234`
`paid` Required	bit boolean	–	Must be `1`. The value `0` (set to unpaid) is rejected with an error. Allowed values `1` – Set the invoice to paid. `0` – Not supported; returns an error. Example: `1`
`PaidDate`	datetime dateTime	NULL	Entry date of the booking. NULL uses the current date and time. Must not be in the future. Example: `2024-05-14T10:30:00`
`eventID`	varchar(3) string	NULL	ID of the customer account event to book (`CustomerAccountEvents.EventID`). Although it has a default, it is mandatory. The event must be manual (`IsManual = 1`) and positive (`OriginalAmountMultiply = 1`). Example: `MZE`
`PaidSum`	money decimal	NULL	Paid amount. It is passed on but not used for the booking; the full open amount is always booked. Example: `119.00`

Result set 1 · On success

Status row confirming that the manual booking event was created.

Column	Type	Description
`Status`	varchar(7) string	Always `Success`.
`Message` Nullable	varchar(80) string	Confirmation text containing the invoice number.

Result set 2 · If an error reaches the wrapper's CATCH block

Status row with the error message.

Column	Type	Description
`Status`	varchar(5) string	Always `Error`.
`Message` Nullable	nvarchar(4000) string	Text of the error (`ERROR_MESSAGE()`).

Response example

<SqlRowSet1>
  <row>
    <Status>Success</Status>
    <Message>Successfully created CA manual booking event for InvoiceNr RE2024001234</Message>
  </row>
</SqlRowSet1>

Status	Message	Cause
Error	Feature "set invoice to unpaid" is not supported	`paid` was sent as `0`. Only setting to paid is supported.
Error	Invoice {InvoiceNr} does not exist	No invoice with the given number exists in `Invoices`.
Error	Invoice {InvoiceNr} is already set to paid	The invoice's paid sum already equals its total.
Error	Parameter @EventID is mandatory	`eventID` was not sent or is NULL.
Error	Event {eventID} either does not exist, is not manually added or is not positive	The event ID is not a manual, positive event in `CustomerAccountEvents`. Use an event with `IsManual = 1` and `OriginalAmountMultiply = 1`.
Error	Paid date is set into the future	`PaidDate` is later than the current server 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:pixiSetInvoicePaid>
      <InvoiceNR>RE2024001234</InvoiceNR>
      <paid>1</paid>
      <!-- <PaidDate>2024-05-14T10:30:00</PaidDate> -->
      <!-- <eventID>MZE</eventID> -->
      <!-- <PaidSum>119.00</PaidSum> -->
    </ns1:pixiSetInvoicePaid>
  </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:pixiSetInvoicePaid>
      <InvoiceNR>RE2024001234</InvoiceNR>
      <paid>1</paid>
      <!-- <PaidDate>2024-05-14T10:30:00</PaidDate> -->
      <!-- <eventID>MZE</eventID> -->
      <!-- <PaidSum>119.00</PaidSum> -->
    </ns1:pixiSetInvoicePaid>
  </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 = [
    'InvoiceNR' => 'RE2024001234',
    'paid' => '1',
    // 'PaidDate' => '2024-05-14T10:30:00',
    // 'eventID' => 'MZE',
    // 'PaidSum' => '119.00',
];

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

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