Invoices Schreiben

pixiSetInvoicePaid

Setzt eine Rechnung auf bezahlt, indem eine manuelle Buchung im Kundenkonto angelegt und mit dem offenen Rechnungsbetrag ausgeglichen wird.

Wrapper um die interne Prozedur pixi_SetInvoicePaid. Die Rückgabe ist eine Statuszeile mit Status und Message.

Ablauf der internen Prozedur:

Die Rechnung wird über InvoiceNR in Invoices gesucht. Gelesen werden Kunde, Gesamtbetrag, bezahlte Summe, Währung und Wechselkurs.
Über Pixi_CA_GetCustomerAccountforInvoice wird der Kundenkonto-Eintrag der Rechnung ermittelt. Der Buchungsbetrag ist der negierte Wert von OpenToMatch dieses Eintrags.
Die Eingaben werden in dieser Reihenfolge geprüft:
- paid muss 1 sein. Das Zurücksetzen auf unbezahlt wird nicht unterstützt.
- Die Rechnung muss existieren.
- Die Rechnung darf nicht bereits vollständig bezahlt sein (total = PayedSum).
- eventID muss angegeben sein.
- Das Ereignis muss in CustomerAccountEvents mit IsManual = 1 und OriginalAmountMultiply = 1 existieren, also ein manuelles, positives Ereignis sein.
- PaidDate (Standard: aktuelles Datum mit Uhrzeit) darf nicht in der Zukunft liegen.
Mit Pixi_CA_InsertManualBookingEvent wird eine manuelle Buchung angelegt:
- Die Buchung verwendet Währung und Wechselkurs der Rechnung.
- Als Benutzername wird API eingetragen.
- Die Buchung wird mit dem Kundenkonto-Eintrag der Rechnung ausgeglichen.

Bei Erfolg liefert der Aufruf Status = Success. Erreicht ein Fehler den Wrapper, liefert er Status = Error mit dem Fehlertext.

Hinweise

PaidSum wirkt sich nicht auf den gebuchten Betrag aus. Ein Wert von 0 wird durch NULL ersetzt, sonst wird der Parameter nicht verwendet. Gebucht wird immer der volle offene Betrag (OpenToMatch) des Kundenkonto-Eintrags der Rechnung.
Die interne Prozedur läuft in einer eigenen Transaktion oder, bei bereits offener Transaktion, in einem Savepoint. XACT_ABORT ist aktiv, bei Fehlern wird zurückgerollt.
Im CATCH-Block ruft die interne Prozedur log.InsertError mit Parameter 1 auf. Dieses Objekt liegt nicht vor. Ob es den Fehler erneut auslöst, ist daher unbekannt. Nur in diesem Fall liefert der Wrapper die Error-Zeile; andernfalls könnte ein fehlgeschlagener Aufruf dennoch Success melden.
Die Ermittlung des Kundenkonto-Eintrags erfolgt vor den Prüfungen. Bei einer nicht existierenden Rechnung wird sie mit NULL-Schlüsseln aufgerufen.
Invoices und CustomerAccountEvents werden mit NOLOCK gelesen.
Welche Tabellen Pixi_CA_InsertManualBookingEvent schreibt, ist aus dem vorliegenden Code nicht ersichtlich.
Die Prüfung auf 'bereits bezahlt' vergleicht total und PayedSum auf exakte Gleichheit. Eine teilbezahlte Rechnung wird mit dem verbleibenden offenen Betrag gebucht.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`InvoiceNR` Pflicht	varchar(20) string	–	Nummer der Rechnung, die auf bezahlt gesetzt werden soll (`Invoices.InvoiceNr`). Beispiel: `RE2024001234`
`paid` Pflicht	bit boolean	–	Muss `1` sein. Der Wert `0` (auf unbezahlt setzen) wird mit einem Fehler abgewiesen. Erlaubte Werte `1` – Rechnung auf bezahlt setzen. `0` – Nicht unterstützt; führt zu einem Fehler. Beispiel: `1`
`PaidDate`	datetime dateTime	NULL	Buchungsdatum. Bei NULL werden das aktuelle Datum und die aktuelle Uhrzeit verwendet. Darf nicht in der Zukunft liegen. Beispiel: `2024-05-14T10:30:00`
`eventID`	varchar(3) string	NULL	ID des Kundenkonto-Ereignisses für die Buchung (`CustomerAccountEvents.EventID`). Trotz Standardwert ist der Parameter Pflicht. Das Ereignis muss manuell (`IsManual = 1`) und positiv (`OriginalAmountMultiply = 1`) sein. Beispiel: `MZE`
`PaidSum`	money decimal	NULL	Bezahlter Betrag. Er wird weitergereicht, aber nicht für die Buchung verwendet; gebucht wird immer der volle offene Betrag. Beispiel: `119.00`

Antwort

Result-Set 1 · Bei Erfolg

Statuszeile, die das Anlegen der manuellen Buchung bestätigt.

Spalte	Typ	Beschreibung
`Status`	varchar(7) string	Immer `Success`.
`Message` Kann leer sein	varchar(80) string	Bestätigungstext mit der Rechnungsnummer.

Result-Set 2 · Wenn ein Fehler den CATCH-Block des Wrappers erreicht

Statuszeile mit der Fehlermeldung.

Spalte	Typ	Beschreibung
`Status`	varchar(5) string	Immer `Error`.
`Message` Kann leer sein	nvarchar(4000) string	Fehlertext (`ERROR_MESSAGE()`).

Beispielantwort

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

Fehlermeldungen

Status	Meldung	Ursache
Error	Feature "set invoice to unpaid" is not supported	`paid` wurde mit `0` übergeben. Unterstützt wird nur das Setzen auf bezahlt.
Error	Invoice {InvoiceNr} does not exist	Zur angegebenen Nummer existiert keine Rechnung in `Invoices`.
Error	Invoice {InvoiceNr} is already set to paid	Die bezahlte Summe der Rechnung entspricht bereits dem Gesamtbetrag.
Error	Parameter @EventID is mandatory	`eventID` wurde nicht übergeben oder ist NULL.
Error	Event {eventID} either does not exist, is not manually added or is not positive	Die Ereignis-ID ist kein manuelles, positives Ereignis in `CustomerAccountEvents`. Es ist ein Ereignis mit `IsManual = 1` und `OriginalAmountMultiply = 1` zu verwenden.
Error	Paid date is set into the future	`PaidDate` liegt nach der aktuellen Serverzeit.

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

Verwendete Tabellen

Invoices · Lesen CustomerAccountEvents · Lesen

SQL-Objekt:: dbo.pipiSetInvoicePaid