Payments Schreiben

pixiCreateBanklineMatch

Ordnet eine Bankzeile einem Auftrag zu, indem ein manueller Bank-Match angelegt wird, und gibt den Auftrag optional frei.

Legt einen manuellen Eintrag in BankMatch an, der eine Bankzeile (BanklineKey) mit einem Auftrag verknüpft.

Es muss entweder OrderNr oder OrderNrExternal übergeben werden, sonst wird eine Fehlerzeile geliefert.
Der Auftrag wird in OrderHeader über OrderNr = @OrderNr OR OrderNrExternal = @OrderNrExternal gesucht. Der offene Betrag ist die Auftragssumme, gerundet auf die Anzahl Nachkommastellen aus der Einstellung NumberOfDecimalPlacesForPrices (Standard 2), abzüglich PaidByCustomer.
Die Abweichung wird als Absolutwert aus verbleibendem Bankbetrag (BankAmount - UsedAmount) minus offenem Betrag berechnet. Ist MaxMatchDelta gesetzt und die Abweichung größer, wird nichts geschrieben und eine Fehlerzeile geliefert.
Existiert bereits eine Zuordnung zwischen diesem Auftrag und dieser Bankzeile, wird eine Fehlerzeile geliefert.
Andernfalls wird eine Zeile in BankMatch mit ManualMatch = 1, dem aktuellen Datum und AmountMatched = dem kleineren Wert aus verbleibendem Bankbetrag und offenem Betrag angelegt.
Bei AutoReleaseOrder = 1 wird die Differenz zwischen OrderTotal und PaidByCustomer des Auftrags erneut geprüft. Ist sie kleiner oder gleich MaxMatchDelta (bzw. 0, wenn nicht gesetzt), werden die Auftragspositionen mit Status HAL auf ANG gesetzt (Auftrag wird freigegeben). Andernfalls wird die gerade angelegte Zuordnung wieder gelöscht.

Der Aufruf liefert immer genau eine Zeile mit Status, Message und den aktuellen Werten der Bankzeile.

Hinweise

Status zeigt das Ergebnis der Freigabe nicht an: Nach dem Insert ist Status immer OK und Message immer leer, auch wenn die Zuordnung wieder gelöscht wurde, weil der Auftrag nicht freigegeben werden konnte. Bei Bedarf den Auftrag bzw. BankMatch anschließend prüfen.
Die Freigabeprüfung setzt voraus, dass PaidByCustomer nach dem Insert aktualisiert wurde. Der Code selbst aktualisiert diesen Wert nicht; vermutlich geschieht das über Logik außerhalb dieser Prozedur (z. B. einen Trigger), die hier nicht sichtbar ist. Ist PaidByCustomer NULL, wird der Auftrag nie freigegeben und die Zuordnung entfernt.
Werden OrderNr und OrderNrExternal gleichzeitig übergeben, kann der OR-Filter mehrere Aufträge treffen; dann wird einer davon beliebig verwendet.
Die Existenz der Bankzeile wird nicht geprüft. Bei nicht vorhandenem BanklineKey wird keine Zuordnung angelegt, Status ist trotzdem OK. Der Match-Schlüssel wird dann über IDENT_CURRENT('BankMatch') ermittelt, das nicht sitzungsbezogen ist; zusammen mit AutoReleaseOrder = 1 und fehlgeschlagener Freigabeprüfung kann so eine fremde BankMatch-Zeile gelöscht werden. Dasselbe Risiko besteht bei parallelen Inserts.
Ist UsedAmount NULL, wird AmountMatched NULL (kein ISNULL im Insert), während die Abweichungsprüfung den Wert als 0 behandelt.
Lesezugriffe verwenden NOLOCK. Die Verarbeitung läuft in einer Transaktion, die nach der Auftragssuche in allen Zweigen committet wird.
Fehler bei der Freigabe (GOS_ReleaseOnHold) werden in LogTable protokolliert und erneut ausgelöst; sie erreichen den Aufrufer als SqlMessage.
Freigegebene Auftragspositionen erhalten UpdateEmp = BanklineMatch - API (payments), gekürzt auf 20 Zeichen.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`BanklineKey` Pflicht	int	–	Schlüssel der Bankzeile (`BankLines.BankLineKey`), die zugeordnet werden soll. Beispiel: `4711`
`OrderNr`	int	NULL	Pixi-Auftragsnummer. Entweder dieser Wert oder `OrderNrExternal` muss übergeben werden. Beispiel: `100234`
`OrderNrExternal`	varchar(50) string	NULL	Externe Auftragsnummer (z. B. Shop-Bestellnummer). Wird verwendet, wenn `OrderNr` nicht übergeben wird. Beispiel: `SHOP-2024-005871`
`MaxMatchDelta`	money decimal	NULL	Maximal zulässige Abweichung zwischen verbleibendem Bankbetrag und offenem Auftragsbetrag. Bei NULL erfolgt vor der Zuordnung keine Prüfung; für die Freigabeprüfung gilt NULL als 0. Beispiel: `0.05`
`AutoReleaseOrder`	bit boolean	0	Bei 1 wird der Auftrag nach der Zuordnung freigegeben, wenn die Restdifferenz innerhalb von `MaxMatchDelta` liegt; andernfalls wird die neue Zuordnung wieder entfernt. Erlaubte Werte `0` – Nur die Zuordnung anlegen. `1` – Zuordnung anlegen und Auftrag freigeben (Positionen `HAL` → `ANG`); Zuordnung entfernen, wenn der Auftrag innerhalb der Abweichung nicht bezahlt ist. Beispiel: `1`

Antwort

Result-Set 1 · Immer (genau eine Zeile).

Statuszeile mit den aktuellen Werten der Bankzeile. Die Bankzeilen-Spalten sind NULL, wenn die Bankzeile nicht existiert.

Spalte	Typ	Beschreibung
`Status`	varchar(5) string	`OK` bei Erfolg, `ERROR`, wenn eine Prüfung fehlgeschlagen ist.
`Message`	varchar(500) string	Fehlertext; Leerstring bei Erfolg.
`BankLineKey` Kann leer sein	int	Schlüssel der Bankzeile.
`BankAmount` Kann leer sein	decimal	Betrag der Bankzeile.
`UsedAmount` Kann leer sein	decimal	Bereits für Zuordnungen verwendeter Betrag der Bankzeile, wie aktuell gespeichert.

Beispielantwort

<SqlRowSet1>
  <row>
    <Status>OK</Status>
    <Message/>
    <BankLineKey>4711</BankLineKey>
    <BankAmount>119.9000</BankAmount>
    <UsedAmount>0.0000</UsedAmount>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
ERROR	OrderNr or OrderNrExternal must be supplied	Weder `OrderNr` noch `OrderNrExternal` wurde übergeben. Einen der beiden Werte angeben.
ERROR	Order was not found	Kein Auftrag in `OrderHeader` passt zur angegebenen Auftragsnummer. `OrderNr`/`OrderNrExternal` prüfen.
ERROR	The match difference is higher that the defined MaxMatchDelta	Die Abweichung zwischen verbleibendem Bankbetrag und offenem Auftragsbetrag überschreitet `MaxMatchDelta`. Toleranz erhöhen oder manuell zuordnen.
ERROR	Bankline match already exists	Diese Bankzeile ist in `BankMatch` bereits diesem Auftrag zugeordnet.
RAISERROR	%s	Beim Freigeben des Auftrags (`GOS_ReleaseOnHold`) ist ein Fehler aufgetreten; die ursprüngliche SQL-Fehlermeldung wird in `LogTable` protokolliert und erneut ausgelöst.

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:pixiCreateBanklineMatch>
      <BanklineKey>4711</BanklineKey>
      <!-- <OrderNr>100234</OrderNr> -->
      <!-- <OrderNrExternal>SHOP-2024-005871</OrderNrExternal> -->
      <!-- <MaxMatchDelta>0.05</MaxMatchDelta> -->
      <!-- <AutoReleaseOrder>1</AutoReleaseOrder> -->
    </ns1:pixiCreateBanklineMatch>
  </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:pixiCreateBanklineMatch>
      <BanklineKey>4711</BanklineKey>
      <!-- <OrderNr>100234</OrderNr> -->
      <!-- <OrderNrExternal>SHOP-2024-005871</OrderNrExternal> -->
      <!-- <MaxMatchDelta>0.05</MaxMatchDelta> -->
      <!-- <AutoReleaseOrder>1</AutoReleaseOrder> -->
    </ns1:pixiCreateBanklineMatch>
  </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 = [
    'BanklineKey' => '4711',
    // 'OrderNr' => '100234',
    // 'OrderNrExternal' => 'SHOP-2024-005871',
    // 'MaxMatchDelta' => '0.05',
    // 'AutoReleaseOrder' => '1',
];

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

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

Verwendete Tabellen

OrderHeader · Lesen BankLines · Lesen BankMatch · Schreiben Numbers · Lesen Settings · Lesen Orderlines · Schreiben LogTable · Schreiben

SQL-Objekt:: dbo.pipiCreateBanklineMatch