Payments Schreiben

pixiCACreateManualBooking

Legt eine manuelle Buchung im Kundenkonto an und gleicht sie optional mit einem vorhandenen Kontoeintrag oder einer Rechnung ab.

Legt eine manuelle Buchung (zum Beispiel eine manuelle Zahlung oder eine Korrektur) im Kundenkonto des Kunden CustKey an.

Ablauf:

EventDate wird auf das aktuelle Datum mit Uhrzeit gesetzt, wenn kein Wert übergeben wird.
Ist MatchToInvoiceNr gesetzt, wird der neueste Kundenkontoeintrag (MAX(CustomerAccountKey)) gesucht, der sich auf diese Rechnung bezieht. Die Rechnung muss zu CustKey gehören. Der gefundene Schlüssel ersetzt einen in MatchKey übergebenen Wert. Wird kein Eintrag gefunden, wird ein Fehler zurückgegeben.
EventID muss in den Ereignisdefinitionen des Kundenkontos existieren und als manuell gekennzeichnet sein (IsManual = 1).
EventDate darf nicht in der Zukunft liegen.
Wird CurrencyId nicht übergeben, wird die Basiswährung des Shops verwendet, zu dem der Kunde gehört.
Die Buchung wird mit dem Benutzernamen API angelegt. Der Wechselkurs wird automatisch anhand von Shop, Währung und EventDate ermittelt.
Ist ein Abgleichsschlüssel bekannt (aus MatchToInvoiceNr oder MatchKey), wird der neue Eintrag mit diesem Eintrag abgeglichen. Der Abgleich erfolgt nur, wenn beide Einträge noch einen offenen Betrag haben, die Vorzeichen der beiden Einträge entgegengesetzt sind, Amount nicht 0 ist und der Betrag des Zieleintrags nicht 0 ist. Abgeglichen wird der kleinere der beiden offenen Beträge.

Der gesamte Aufruf läuft in einer Transaktion. Zurückgegeben wird eine Zeile mit ReturnCode = OK bei Erfolg oder ERROR mit dem Fehlertext.

Hinweise

Validierungsfehler und Fehler bei der Wechselkursermittlung setzen die Transaktion zurück und liefern eine ERROR-Zeile.
Fehler beim Einfügen oder beim Abgleich innerhalb der internen Buchungsprozedur werden dort abgefangen und nicht weitergegeben. In diesem Fall kann der Aufruf trotzdem OK liefern, obwohl keine Buchung angelegt wurde. Bei Bedarf sollte das Kundenkonto anschließend geprüft werden.
Der Kundenkontoeintrag zur neuen Buchung wird über ManualBookingRef gelesen. Er wird vermutlich durch Logik an der Tabelle der manuellen Buchungen erzeugt, die hier nicht sichtbar ist.
Die Wechselkursermittlung (pixi.GetExchRateID) und die Abgleichsprozedur (Pixi_CA_InsertMatch) liegen nicht vor; ihr genaues Verhalten ist unbekannt.
Bei MatchKey wird nicht geprüft, ob der Eintrag zum Kunden gehört. MatchToInvoiceNr wird geprüft und ist daher vorzuziehen.
CustKey wird nicht ausdrücklich geprüft. Bei einem unbekannten Kunden bleibt CurrencyId NULL, wenn kein Wert übergeben wird.
Der Fehlertext für ein Datum in der Zukunft spricht von einem "paid date"; gemeint ist EventDate.
Abfragen verwenden NOLOCK.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`CustKey` Pflicht	int	–	Schlüssel des Kunden, in dessen Kundenkonto gebucht wird. Beispiel: `10234`
`EventID` Pflicht	varchar(3) string	–	ID des zu buchenden Kundenkonto-Ereignisses. Das Ereignis muss existieren und als manuell gekennzeichnet sein. Beispiel: `MPY`
`Amount` Pflicht	money decimal	–	Betrag der Buchung. Beispiel: `49.90`
`EventDate`	datetime dateTime	NULL	Datum und Uhrzeit der Buchung. Darf nicht in der Zukunft liegen. Bei `NULL` wird das aktuelle Datum mit Uhrzeit verwendet. Beispiel: `2024-03-15T10:30:00`
`Comment`	varchar(512) string	NULL	Kommentar, der als Referenz der Buchung gespeichert wird. `NULL` wird als Leerstring gespeichert. Beispiel: `Bank transfer received 15.03.`
`MatchToInvoiceNr`	varchar(20) string	NULL	Nummer einer Rechnung dieses Kunden. Die neue Buchung wird mit dem neuesten Kontoeintrag dieser Rechnung abgeglichen. Hat Vorrang vor `MatchKey`. Beispiel: `RE2024001234`
`MatchKey`	int	NULL	Schlüssel des Kundenkontoeintrags (`CustomerAccountKey`), mit dem die neue Buchung abgeglichen wird. Wird ignoriert, wenn `MatchToInvoiceNr` gesetzt ist. Beispiel: `558812`
`CurrencyId`	smallint int	NULL	Währung der Buchung. Bei `NULL` wird die Basiswährung des Shops des Kunden verwendet. Beispiel: `1`

Antwort

Result-Set 1 · Bei einem Validierungs- oder Verarbeitungsfehler (Transaktion wird zurückgesetzt)

Fehlerzeile.

Spalte	Typ	Beschreibung
`ReturnCode`	varchar(5) string	Immer `ERROR`.
`ErrorMessage` Kann leer sein	nvarchar(4000) string	Text des Fehlers.

Result-Set 2 · Bei Erfolg (Transaktion bestätigt)

Erfolgszeile.

Spalte	Typ	Beschreibung
`ReturnCode`	varchar(2) string	Immer `OK`.
`ErrorMessage`	varchar(44) string	Fester Text `Event successfully added to customer account`.

Beispielantwort

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

Fehlermeldungen

Status	Meldung	Ursache
ERROR	Invoice {MatchToInvoiceNr} does not exist or does not belong to this customer	`MatchToInvoiceNr` wurde übergeben, aber es gibt keinen Kundenkontoeintrag zu einer Rechnung mit dieser Nummer, die zu `CustKey` gehört.
ERROR	Parameter @EventID is mandatory	`EventID` wurde als `NULL` übergeben.
ERROR	Event {EventID} either does not exist or is not manual	Die Ereignis-ID ist unbekannt oder das Ereignis ist nicht als manuell gekennzeichnet. Ein Ereignis mit `IsManual = 1` verwenden.
ERROR	Paid date is set into the future	`EventDate` liegt nach dem aktuellen Datum mit Uhrzeit.

Beispiele

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);

Verwendete Tabellen

CustomerAccount · Lesen Invoices · Lesen CustomerAccountEvents · Lesen Shops · Lesen Customers · Lesen CustomerAccountManualBookings · Schreiben

SQL-Objekt:: dbo.pipiCACreateManualBooking