Pixi-API-Dokumentation

Inoffiziell · von koempf24.de

Postman-Collection
Invoices Schreiben

pixiCreatePOSInvoice

Legt aus einem XML-Dokument eine neue POS-Rechnung an oder ergänzt eine offene um Positionen und bucht die verkauften Artikel aus dem Bestand aus.

Legt eine Kassenrechnung (POS-Rechnung) für eine Kasse an. Alle Daten werden in einem XML-Dokument im Parameter XML übergeben.

Einlesen

  • Kopfdaten aus POSINVOICE/HEADER: REGISTERID (Pflicht), POSHEADERKEY (optional, eine bestehende Rechnung, die ergänzt wird), COMMENT, CUSTOMERNREXTERNAL (optional) und GENERALBIN (optionaler allgemeiner POS-Lagerplatz).
  • Positionen aus POSINVOICE/LINES/LINE: ITEMNRINT, QUANTITY, PRICE, DISCOUNTPERCENT (Standard 0) und BIN (bevorzugter Lagerplatz, Standard leer). COMMAND wird gelesen, aber nicht verwendet.

Ermittlungen

  • Der Kunde wird über Customers.CustomerNrExternal gesucht; sein Adressschlüssel wird an der Rechnung gespeichert.
  • Die offene POS-Session (EndTime ist NULL) der Kasse mit der neuesten StartTime liefert Lager, Session-ID und Benutzernamen.
  • Der Artikel jeder Position wird über ItemNrInt gesucht; dessen EAN/UPC wird übernommen.

Prüfungen (in dieser Reihenfolge; der erste Fehler beendet den Aufruf mit einer ERROR-Zeile)

  1. REGISTERID ist vorhanden.
  2. Bei Angabe von POSHEADERKEY existiert die Rechnung in POSheader2 und ihr Status ist weder CLO noch STO.
  3. Für die Kasse existiert eine offene POS-Session.
  4. Alle Artikel existieren.
  5. Bei Angabe von CUSTOMERNREXTERNAL existiert der Kunde.
  6. Keine Menge ist negativ.
  7. DISCOUNTPERCENT liegt zwischen 0 und 100.

Ausführung (in einer Transaktion)

  • Ohne POSHEADERKEY wird über die interne Prozedur Pixi_POSNewInvoice ein neuer Rechnungskopf angelegt (Belegart INV). Diese Prozedur schreibt zusätzlich ein Session-Ereignis und veröffentlicht das MQ-Ereignis POSInoviceCreated.
  • Der Kopf wird aktualisiert: Kundenadresse, InvoiceComment, Änderungsbenutzer und Änderungsdatum.
  • Für jede Position:
    • Eine POSitem2-Zeile mit Menge, Preis, Rabatt und EAN/UPC wird angelegt.
    • Entnahme-Lagerplätze werden vorgeschlagen, mit BIN als Prioritäts-Lagerplatz und GENERALBIN als allgemeinem Lagerplatz, in aufsteigender Reihenfolge.
    • Die Vorschläge werden in POSItemBinSelection gespeichert.
    • Der Bestand wird von den Lagerplätzen ausgebucht (Aktionstyp 4, Lagerbewegungsreferenzen SMORef 15 / SMTRef 12).
    • Schlägt die Buchung einer Position fehl, wird der gesamte Aufruf zurückgerollt.
  • Bei Erfolg wird eine Zeile mit ReturnCode = OK und dem Rechnungsschlüssel in Message zurückgegeben.

Hinweise

  • Spaltenname unterscheidet sich in der Schreibweise: Die Erfolgszeile hat die Spalte Message, die Fehlerzeile die Spalte MESSAGE. XML-Elementnamen unterscheiden Groß- und Kleinschreibung, daher muss ein Client beide auslesen.
  • XML-Parsing außerhalb der Fehlerbehandlung: sp_xml_preparedocument läuft außerhalb des TRY-Blocks. Ein NULL-Wert oder ungültiges XML kommt daher als SqlMessage zurück und nicht als ERROR-Zeile. Das XML-Dokument-Handle wird nie mit sp_xml_removedocument freigegeben.
  • Datentypfehler: Nicht konvertierbare Werte im XML (z. B. nicht numerische QUANTITY oder PRICE) führen zu einer ERROR-Zeile mit der SQL-Server-Meldung.
  • Überschriebene Kopffelder: Wird eine bestehende Rechnung ergänzt, werden die Positionen angehängt; vorhandene Positionen bleiben unverändert. PHCusAddrKey und InvoiceComment werden immer überschrieben, mit NULL, wenn CUSTOMERNREXTERNAL oder COMMENT fehlt.
  • Neue Rechnung bei Schlüssel 0: Ein leerer oder 0-Wert in POSHEADERKEY wird als „neu anlegen“ behandelt.
  • Irreführende Artikel-Fehlermeldung: Die Meldung 'Item not found' enthält die Artikelnummer einer beliebigen Position, nicht unbedingt die des fehlenden Artikels. Fehlt dort ITEMNRINT, ist die Meldung leer. Die Meldung wird auf 150 Zeichen gekürzt.
  • Ungeprüfte Positionswerte: Eine NULL-Menge und ein NULL-Preis werden nicht abgewiesen; eine Menge von 0 wird akzeptiert. PRICE wird wie übergeben gespeichert und nicht aus den Artikelstammdaten übernommen.
  • Chargen und MHD: Die Bestandsbuchung übergibt keine Charge und kein Mindesthaltbarkeitsdatum, daher kommt nur Lagerplatzbestand ohne Charge und ohne MHD in Frage. Chargen- oder MHD-geführte Artikel scheitern daher voraussichtlich mit einer Bestandsmeldung.
  • Lagerplatzlogik nicht beigefügt: Die eigentliche Lagerplatzwahl erfolgt in Pixi_POS_GetTakeOutBins und Pixi_POSSuggestBinTakeOut. Der Bestand wird in Pixi_InvBinTakeOut ausgebucht. Diese Objekte sind nicht beigefügt, daher lassen sich die genaue Lagerplatzreihenfolge und die Entnahmemeldungen hier nicht dokumentieren.
  • Nebeneffekte der aufgerufenen Prozeduren: POSSession_event und POSBinTrack werden geschrieben, das MQ-Ereignis POSInoviceCreated wird veröffentlicht, und Entnahmefehler werden in LogTable protokolliert.
  • Transaktion: Alle Änderungen laufen in einer Transaktion und werden bei jedem Fehler zurückgerollt. Lesezugriffe verwenden NOLOCK, die Kopfaktualisierung ROWLOCK.

Parameter

Parameter Typ Standardwert Beschreibung
XML
varchar(max)
xml		 NULL

XML-Dokument mit dem Wurzelelement POSINVOICE. Es enthält ein HEADER-Element (REGISTERID, POSHEADERKEY, COMMENT, CUSTOMERNREXTERNAL, GENERALBIN) und LINES/LINE-Elemente (ITEMNRINT, QUANTITY, PRICE, DISCOUNTPERCENT, BIN, COMMAND). Werte können als Kindelemente oder als Attribute angegeben werden. Obwohl der SQL-Standardwert NULL ist, funktioniert der Aufruf ohne diesen Parameter nicht.

Beispiel:

<POSINVOICE>
  <HEADER>
    <REGISTERID>KASSE01</REGISTERID>
    <POSHEADERKEY/>
    <COMMENT>Walk-in sale</COMMENT>
    <CUSTOMERNREXTERNAL>CUST-10023</CUSTOMERNREXTERNAL>
    <GENERALBIN>POS-GENERAL</GENERALBIN>
  </HEADER>
  <LINES>
    <LINE>
      <ITEMNRINT>4711</ITEMNRINT>
      <QUANTITY>2</QUANTITY>
      <PRICE>19.99</PRICE>
      <DISCOUNTPERCENT>10</DISCOUNTPERCENT>
      <BIN>A-01-02</BIN>
      <COMMAND>ADD</COMMAND>
    </LINE>
    <LINE>
      <ITEMNRINT>4712</ITEMNRINT>
      <QUANTITY>1</QUANTITY>
      <PRICE>5.50</PRICE>
      <DISCOUNTPERCENT>0</DISCOUNTPERCENT>
      <BIN/>
      <COMMAND>ADD</COMMAND>
    </LINE>
  </LINES>
</POSINVOICE>

Antwort

Result-Set 1 · Bei Erfolg

Statuszeile mit dem Schlüssel der angelegten oder ergänzten POS-Rechnung.

Spalte Typ Beschreibung
ReturnCode varchar(2)
string

Immer OK.
Message
Kann leer sein
 int

POSheaderKey der POS-Rechnung.

Result-Set 2 · Bei jedem Fehler während der Verarbeitung (Prüfung, Datenkonvertierung, Bestandsbuchung)

Fehlerzeile. Alle Änderungen wurden zurückgerollt.

Spalte Typ Beschreibung
ReturnCode varchar(5)
string

Immer ERROR.
MESSAGE
Kann leer sein
 nvarchar(4000)
string

Fehlertext (ERROR_MESSAGE()). Spaltenname beachten: in Großbuchstaben.

Beispielantwort

<SqlRowSet1>
  <row>
    <ReturnCode>OK</ReturnCode>
    <Message>10452</Message>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status Meldung Ursache
ERROR Mandatory data not present (REGISTERID)! `HEADER/REGISTERID` fehlt oder ist leer. Die Kassen-ID muss immer übergeben werden.
ERROR Unable to edit existing invoice (does not exist or wrong status) `POSHEADERKEY` wurde angegeben, aber die Rechnung existiert nicht oder hat den Status `CLO` oder `STO`. Nur offene Rechnungen können ergänzt werden.
ERROR Error creating new invoice- POS is not started! Für die Kasse existiert keine offene POS-Session (ohne Endzeit). Zuerst die POS-Session starten.
ERROR Item not found, ItemNrInt:{ItemNrInt} Mindestens eine `ITEMNRINT` passt zu keinem Artikel. Die Nummer in der Meldung stammt aus einer beliebigen Position und ist nicht unbedingt die fehlende.
ERROR Customer not found! `CUSTOMERNREXTERNAL` wurde angegeben, passt aber zu keinem Kunden. Externe Kundennummer prüfen oder weglassen.
ERROR Only positives for item Quantity! Eine Position hat eine negative `QUANTITY`.
ERROR DISCOUNTPERCENT can be from 0 to 100! Eine Position hat einen `DISCOUNTPERCENT` unter 0 oder über 100.
ERROR Adding item to invoice line failed, ItemKey:{ItemKey}, message:{Message} Die Ausbuchung des Bestands von den Lagerplätzen ist für eine Position fehlgeschlagen, typischerweise wegen zu geringen Bestands. Mögliche Meldungen sind `NoItemStockInGeneral`, `ItemNotonPOS`, `BundleNotonPOS`, `NoStockOnPOS`, 'One of the bundled items has insufficient quantity on stock! (...)', 'Internal error' oder eine Meldung der Bestandsentnahme. Der Text wird auf 150 Zeichen gekürzt.

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:pixiCreatePOSInvoice>
      <!-- <XML><![CDATA[<POSINVOICE><HEADER><REGISTERID>KASSE01</REGISTERID><POSHEADERKEY></POSHEADERKEY><COMMENT>Walk-in sale</COMMENT><CUSTOMERNREXTERNAL>CUST-10023</CUSTOMERNREXTERNAL><GENERALBIN>POS-GENERAL</GENERALBIN></HEADER><LINES><LINE><ITEMNRINT>4711</ITEMNRINT><QUANTITY>2</QUANTITY><PRICE>19.99</PRICE><DISCOUNTPERCENT>10</DISCOUNTPERCENT><BIN>A-01-02</BIN><COMMAND>ADD</COMMAND></LINE><LINE><ITEMNRINT>4712</ITEMNRINT><QUANTITY>1</QUANTITY><PRICE>5.50</PRICE><DISCOUNTPERCENT>0</DISCOUNTPERCENT><BIN></BIN><COMMAND>ADD</COMMAND></LINE></LINES></POSINVOICE>]]></XML> -->
    </ns1:pixiCreatePOSInvoice>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Verwendete Tabellen

Customers · Lesen Addresses · Lesen POSSession · Lesen Items · Lesen POSheader2 · Schreiben POSitem2 · Schreiben POSItemBinSelection · Schreiben
SQL-Objekt:
dbo.pipiCreatePOSInvoice
Prozedur zuletzt geändert am 2026-10-05
Dokumentation von claude-opus-5-5 am 2026-10-30 geschrieben