Payments Schreiben

pixiCAInsertMatch

Legt eine Verrechnung (Match) zwischen zwei Kundenkonto-Buchungen mit einem angegebenen Betrag an.

Verknüpft zwei Kundenkonto-Buchungen, z. B. eine Zahlung und eine Rechnung, mit einem Verrechnungsbetrag.

Zuerst läuft die allgemeine API-Hülle. Sie prüft das Aufruffrequenz-Limit für pipiCAInsertMatch und speichert den Zeitpunkt des Aufrufs. Ist das Limit überschritten, wird eine Zeile mit ResultCode 502 und ResultText geliefert, und es passiert nichts weiter.
Ist CAref1, CAref2 oder MatchAmount NULL, wird eine Statuszeile mit ReturnCode = ERROR und ErrorMessage geliefert. Es werden keine Daten geschrieben.
Andernfalls wird ein Datensatz in CustomerAccountMatch angelegt:
- CAref1 und CAref2 werden wie übergeben gespeichert.
- AbsoluteMatchAmount erhält MatchAmount, auf 2 Nachkommastellen gerundet.
- Anlage- und Änderungsbenutzer werden auf API gesetzt, jeweils mit aktuellem Datum und aktueller Uhrzeit.

Bei Erfolg liefert der Aufruf keine Ergebnismenge.

Hinweise

Das Einfügen läuft in einer eigenen Transaktion bzw. in einem Savepoint, wenn bereits eine Transaktion offen ist.
SQL-Fehler beim Einfügen werden abgefangen, zurückgerollt und über log.InsertError protokolliert; dieses Objekt liegt nicht vor. Beispiele sind Constraint-Verletzungen bei nicht existierenden CAref-Werten. Der Aufrufer erhält in diesem Fall keine Fehlerzeile, sodass Erfolg und fehlgeschlagenes Einfügen anhand der Antwort allein nicht unterscheidbar sind.
Der Code prüft nicht, ob CAref1 und CAref2 existieren, zum selben Kunden gehören oder ob der Betrag zu den offenen Salden passt. Solche Prüfungen hängen von hier nicht sichtbaren Tabellen-Constraints ab.
Die ID des neuen Match-Datensatzes wird nur als interner Rückgabewert der Prozedur verwendet und nicht an den SOAP-Aufrufer geliefert.
CAref1, CAref2 und MatchAmount haben keinen Standardwert. Werden sie im Request weggelassen, entsteht ein SQL-Fehler wegen des fehlenden Parameters. Die ERROR-Zeile erscheint nur, wenn sie explizit als NULL übergeben werden.
Der Fehlertext enthält einen Tippfehler: Er nennt CAref1 zweimal statt CAref1 und CAref2.
Frequenz-Limits werden in API_CONTROL (MIN_BREATHING_MSEC) konfiguriert.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`CAref1` Pflicht	int	–	Schlüssel der ersten zu verrechnenden Kundenkonto-Buchung. Beispiel: `15234`
`CAref2` Pflicht	int	–	Schlüssel der zweiten zu verrechnenden Kundenkonto-Buchung. Beispiel: `15240`
`MatchAmount` Pflicht	money decimal	–	Zu verrechnender Betrag. Er wird auf 2 Nachkommastellen gerundet und als `AbsoluteMatchAmount` gespeichert. Beispiel: `49.90`
`ResultCode` OUTPUT	char(3) string	NULL	Ausgabe: Ergebniscode der API-Hülle, `200` bei zugelassenem Aufruf oder `502` bei überschrittenem Frequenz-Limit. Erlaubte Werte `200` – Aufruf zugelassen (OK) `502` – Frequenz-Limit überschritten
`ResultText` OUTPUT	varchar(1024) string	NULL	Ausgabe: Text zu `ResultCode`, entweder `OK` oder die Meldung zum Frequenz-Limit.

Antwort

Result-Set 1 · Nur wenn das Aufruffrequenz-Limit für diese Funktion überschritten ist

Statuszeile der API-Hülle zur Frequenzbegrenzung.

Spalte	Typ	Beschreibung
`ResultCode`	char(3) string	In diesem Fall immer `502`.PLACEHOLDER
`ResultText`	varchar(1024) string	Meldung mit der verbleibenden Wartezeit in Millisekunden.

Result-Set 2 · Wenn `CAref1`, `CAref2` oder `MatchAmount` NULL ist

Fehlerzeile der Eingabeprüfung.

Spalte	Typ	Beschreibung
`ReturnCode`	varchar(5) string	Immer `ERROR`.
`ErrorMessage`	varchar(46) string	Fehlertext.

Beispielantwort

<SqlRowSet1>
  <row>
    <ReturnCode>ERROR</ReturnCode>
    <ErrorMessage>CAref1, CAref1 and MatchAmount cannot be NULL</ErrorMessage>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
ERROR	CAref1, CAref1 and MatchAmount cannot be NULL	`CAref1`, `CAref2` oder `MatchAmount` wurde als NULL übergeben. Alle drei Werte übergeben.
502	({value}) Frequency quote exceeded. Next call to this function can be made in ca. {value} milliseconds	Die Funktion wurde vor Ablauf des in `API_CONTROL` konfigurierten Mindestabstands erneut aufgerufen. Vor einem erneuten Versuch die angegebene Zeit abwarten.

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:pixiCAInsertMatch>
      <CAref1>15234</CAref1>
      <CAref2>15240</CAref2>
      <MatchAmount>49.90</MatchAmount>
      <!-- <ResultCode>?</ResultCode> -->
      <!-- <ResultText>?</ResultText> -->
    </ns1:pixiCAInsertMatch>
  </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:pixiCAInsertMatch>
      <CAref1>15234</CAref1>
      <CAref2>15240</CAref2>
      <MatchAmount>49.90</MatchAmount>
      <!-- <ResultCode>?</ResultCode> -->
      <!-- <ResultText>?</ResultText> -->
    </ns1:pixiCAInsertMatch>
  </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 = [
    'CAref1' => '15234',
    'CAref2' => '15240',
    'MatchAmount' => '49.90',
    // 'ResultCode' => '?',
    // 'ResultText' => '?',
];

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

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

Verwendete Tabellen

API_STATISTICS · Schreiben API_CONTROL · Lesen CustomerAccountMatch · Schreiben

SQL-Objekt:: dbo.pipiCAInsertMatch