Direct-Fulfillment Schreiben

pixiDFSetStatus

Setzt den Direct-Fulfillment-Status von Auftragspositionen anhand einer XML-Liste von OrderHistory-Schlüsseln und legt optional anschließend DF-Rechnungen an.

Wird von Direct-Fulfillment-Lieferanten genutzt, um den Bearbeitungsstand von Auftragspositionen (versendet, storniert, nicht lieferbar) zusammen mit Versanddatum, Tracking-ID, externer Rechnungsnummer, Charge, MHD und Seriennummer zurückzumelden.

Ablauf

Authentifizierung: Es wird ein Lieferant in Suppliers mit SupplNr = @SupplNr, CustNr = @Secret, nicht deaktiviert und CanDoDirectFulfillment = 1 gesucht. Wird keiner gefunden und ist die Einstellung DFAPIAllowFullAccessWithoutSecret 0 oder nicht vorhanden, bricht der Aufruf mit der Meldung 403 Not Authorized… ab und liefert keine Zeilen.
XML-Auswertung: Alle Elemente /SETDFSTATUS/ITEM (elementbasiert) werden in eine Arbeitstabelle gelesen. Fehlende ERROR/ERRORMSG werden mit 200/leer belegt.
Duplikatprüfung: Kommt derselbe ORDERHISTORYKEY mehrfach mit demselben STATUS vor, wird 500 Duplicate Orderhistorykey and Status. ausgelöst und nichts geändert.
Verarbeitung je Eintrag (in einer Transaktion): Die Auftragsposition wird über OrderHistory.OrderHistKey → OrderLineRef ermittelt, danach wird die interne Prozedur Pixi_UpdateOrderlineDFStatusByOrderlineKey ausgeführt. Diese:
- lehnt den Eintrag ab, wenn die Auftragsposition nicht existiert, bereits im Status FUS oder in einem Endstatus ist, wenn QTY < 1 oder größer als die Positionsmenge ist, oder wenn Charge/MHD für Artikel mit den entsprechenden System-Tags fehlen (nur bei aktiver Einstellung DFRequiredDataForSystemTags);
- teilt die Auftragsposition, wenn QTY kleiner als die aktuelle Menge ist (die gemeldete Menge bleibt auf der ursprünglichen Position, der Rest geht auf eine neue Position im alten Status);
- setzt den Status: STO → STO, NLB → NLB, jeder andere Wert → FUS bei DF-Typ 1, 3 oder leer, sonst BES (dann wird eine Reservierung für den Auftrag angelegt);
- aktualisiert die Auftragsposition mit Status, Versanddatum, Tracking-ID, externer Rechnungsnummer, Charge, MHD und Seriennummer (UpdateEmp = DF API).
Der Ergebnistext je Eintrag wird in ERRORMSG geschrieben; ERROR wird 500, wenn der Text error enthält, sonst 200. Jeder Eintrag wird zusätzlich in LogTable protokolliert.
Alle Einträge werden als eine Ergebnismenge zurückgegeben und die Transaktion wird festgeschrieben.
Ist @CreateInvoices = Y, wird anschließend pipiDFCreateInvoices ohne Parameter ausgeführt.

Hinweise

Teilverarbeitung: Fehler bei einzelnen Einträgen machen die übrigen Einträge nicht rückgängig. Der interne Fehlerzähler wird nie erhöht, die Transaktion wird also immer festgeschrieben; ERROR muss je Zeile geprüft werden.
@SupplNr/@Secret dienen nur der Authentifizierung. Der Code prüft nicht, ob die Auftragspositionen zu diesem Lieferanten gehören.
Die 403-Meldung wird mit Schweregrad 0 ausgelöst, also als Informationsmeldung und nicht als SQL-Fehler. Clients müssen sie explizit auswerten, wenn keine Zeilen zurückkommen.
STATUS wird mit bis zu 13 Zeichen gelesen, aber als varchar(3) verarbeitet; längere Werte werden abgeschnitten, und die Ergebniszeile wird dann eventuell nicht aktualisiert (bleibt bei ERROR 200).
Versanddatum, Tracking-ID und externe Rechnungsnummer werden immer überschrieben; fehlende Elemente setzen diese Felder auf NULL. Charge, MHD und Seriennummer behalten bei leerem Wert ihren bisherigen Inhalt.
BESTBEFOREDATE wird implizit in ein Datum umgewandelt; ungültige Werte führen zu einer Ausnahme.
Bei einer Ausnahme wird die Transaktion zurückgerollt, der Fehler über log.InsertError protokolliert und keine Ergebnismenge geliefert. Fehler, die in der internen Prozedur abgefangen werden, erscheinen ggf. nicht in ERROR.
Treffen mehrere Fehlerbedingungen auf einen Eintrag zu, wird nur die zuletzt gesetzte Meldung geliefert.
@CreateInvoices = 'Y' führt pipiDFCreateInvoices für alle zur Rechnungsstellung bereiten DF-Auftragspositionen aus, nicht nur für die dieses Aufrufs; dies geschieht nach dem Commit und liefert keine Zeilen. Die eigentliche Rechnungserstellung (Pixi_CreateFulfillmentIncoices) liegt nicht vor.
Lesezugriffe verwenden NOLOCK.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`XML` Pflicht	varchar(max) xml	–	XML-Dokument mit einem `ITEM` je Statusmeldung unter dem Wurzelelement `SETDFSTATUS`. Elemente: `ORDERHISTORYKEY`, `STATUS` (`STO` = Storno, `NLB` = nicht lieferbar, andere Werte = bearbeitet/versendet), `QTY`, `SHIPDATE`, `TRACKINGID`, `INVOICENREXTERNAL`, `BATCHNUMBER`, `BESTBEFOREDATE`, `SERIALNUMBER`; `ERROR`/`ERRORMSG` werden gelesen, aber durch das Ergebnis überschrieben. Beispiel: `<SETDFSTATUS> <ITEM> <ORDERHISTORYKEY>784512</ORDERHISTORYKEY> <STATUS>FUS</STATUS> <QTY>2</QTY> <SHIPDATE>2024-05-14T10:30:00</SHIPDATE> <TRACKINGID>00340434161094042557</TRACKINGID> <INVOICENREXTERNAL>RE-2024-0815</INVOICENREXTERNAL> <BATCHNUMBER>B2024-17</BATCHNUMBER> <BESTBEFOREDATE>2025-12-31</BESTBEFOREDATE> <SERIALNUMBER>SN-000123</SERIALNUMBER> <ERROR/> <ERRORMSG/> </ITEM> </SETDFSTATUS>`
`CreateInvoices`	varchar(1) string	N	Bei `Y` wird nach erfolgreichem Lauf `pipiDFCreateInvoices` ausgeführt. Erlaubte Werte `Y` – Anschließend DF-Rechnungen anlegen `N` – Keine Rechnungen anlegen Beispiel: `Y`
`SupplNr`	varchar(4) string	NULL	Lieferantennummer des Direct-Fulfillment-Lieferanten, dient der Authentifizierung. Beispiel: `L042`
`Secret`	varchar(20) string	NULL	Geheimwert des Lieferanten; wird mit `Suppliers.CustNr` verglichen. Kann nur entfallen, wenn die Einstellung `DFAPIAllowFullAccessWithoutSecret` aktiv ist. Beispiel: `K7x9Pq2mZ4`

Antwort

Result-Set 1 · Nach bestandener Authentifizierung und Duplikatprüfung, sofern bei der Verarbeitung keine Ausnahme auftritt

Eine Zeile je ITEM des Eingabe-XML mit den gesendeten Werten und dem Verarbeitungsergebnis.

Spalte	Typ	Beschreibung
`ORDERHISTORYKEY` Kann leer sein	int	OrderHistory-Schlüssel wie gesendet
`STATUS` Kann leer sein	varchar(13) string	Status wie gesendet
`QTY` Kann leer sein	int	Gemeldete Menge wie gesendet
`SHIPDATE` Kann leer sein	datetime dateTime	Versanddatum wie gesendet
`TRACKINGID` Kann leer sein	varchar(100) string	Tracking-ID wie gesendet
`INVOICENREXTERNAL` Kann leer sein	varchar(20) string	Externe Rechnungsnummer wie gesendet
`BATCHNUMBER` Kann leer sein	varchar(50) string	Charge wie gesendet
`BESTBEFOREDATE` Kann leer sein	varchar(50) string	MHD wie gesendet (Text)
`SERIALNUMBER` Kann leer sein	varchar(50) string	Seriennummer wie gesendet
`ERROR` Kann leer sein	varchar(100) string	`200` = verarbeitet, `500` = abgelehnt (Meldung enthält `error`)
`ERRORMSG` Kann leer sein	varchar(max) string	Ergebnistext: leer bei Erfolg, `INFO: Split Orderline …` bei Teilung oder eine `ERROR: …`-Meldung

Beispielantwort

<SqlRowSet1>
  <row>
    <ORDERHISTORYKEY>784512</ORDERHISTORYKEY>
    <STATUS>FUS</STATUS>
    <QTY>2</QTY>
    <SHIPDATE>2024-05-14T10:30:00</SHIPDATE>
    <TRACKINGID>00340434161094042557</TRACKINGID>
    <INVOICENREXTERNAL>RE-2024-0815</INVOICENREXTERNAL>
    <BATCHNUMBER>B2024-17</BATCHNUMBER>
    <BESTBEFOREDATE>2025-12-31</BESTBEFOREDATE>
    <SERIALNUMBER>SN-000123</SERIALNUMBER>
    <ERROR>200</ERROR>
    <ERRORMSG/>
  </row>
  <row>
    <ORDERHISTORYKEY>784513</ORDERHISTORYKEY>
    <STATUS>STO</STATUS>
    <ERROR>500</ERROR>
    <ERRORMSG>ERROR: Orderline was already processed.</ERRORMSG>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
RAISERROR	403 Not Authorized. Secret or SupplNr is incorrect.	Kein aktiver DF-Lieferant passt zu `@SupplNr` und `@Secret`, und die Einstellung `DFAPIAllowFullAccessWithoutSecret` ist nicht aktiv. Wird mit Schweregrad 0 (Information) ausgelöst; es werden keine Zeilen geliefert.
RAISERROR	500 Duplicate Orderhistorykey and Status.	Das XML enthält denselben `ORDERHISTORYKEY` mit demselben `STATUS` mehrfach. Jede Kombination nur einmal senden.
500	ERROR: Orderline not existing	Zum `ORDERHISTORYKEY` wurde keine Auftragsposition gefunden.
500	ERROR: Batch number and Best Before Date are required for the item Id {ItemId}	Einstellung `DFRequiredDataForSystemTags` ist aktiv, der Artikel ist für Charge und MHD getaggt und beide fehlen.
500	ERROR: Best Before Date is required for the item Id {ItemId}	Einstellung `DFRequiredDataForSystemTags` ist aktiv und das erforderliche MHD des Artikels fehlt.
500	ERROR: Batch number is required for the item Id {ItemId}	Einstellung `DFRequiredDataForSystemTags` ist aktiv und die erforderliche Charge des Artikels fehlt.
500	ERROR: Only positive values bigger than 1 are allowed! Sent value is {Qty}	`QTY` ist kleiner als 1.
500	ERROR: Value {Qty} is too big, MAX value allowed:{OriginalQty}	`QTY` ist größer als die Menge der Auftragsposition.
500	ERROR: Orderline was already processed.	Die Auftragsposition ist bereits im Status `FUS` oder in einem Endstatus.
500	ERROR: Error Creating Reservation	Wird angehängt, wenn das Anlegen der Reservierung für eine auf `BES` gesetzte Position einen Fehler meldet.

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:pixiDFSetStatus>
      <XML><![CDATA[<SETDFSTATUS><ITEM><ORDERHISTORYKEY>784512</ORDERHISTORYKEY><STATUS>FUS</STATUS><QTY>2</QTY><SHIPDATE>2024-05-14T10:30:00</SHIPDATE><TRACKINGID>00340434161094042557</TRACKINGID><INVOICENREXTERNAL>RE-2024-0815</INVOICENREXTERNAL><BATCHNUMBER>B2024-17</BATCHNUMBER><BESTBEFOREDATE>2025-12-31</BESTBEFOREDATE><SERIALNUMBER>SN-000123</SERIALNUMBER><ERROR></ERROR><ERRORMSG></ERRORMSG></ITEM></SETDFSTATUS>]]></XML>
      <!-- <CreateInvoices>Y</CreateInvoices> -->
      <!-- <SupplNr>L042</SupplNr> -->
      <!-- <Secret>K7x9Pq2mZ4</Secret> -->
    </ns1:pixiDFSetStatus>
  </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:pixiDFSetStatus>
      <XML><![CDATA[<SETDFSTATUS><ITEM><ORDERHISTORYKEY>784512</ORDERHISTORYKEY><STATUS>FUS</STATUS><QTY>2</QTY><SHIPDATE>2024-05-14T10:30:00</SHIPDATE><TRACKINGID>00340434161094042557</TRACKINGID><INVOICENREXTERNAL>RE-2024-0815</INVOICENREXTERNAL><BATCHNUMBER>B2024-17</BATCHNUMBER><BESTBEFOREDATE>2025-12-31</BESTBEFOREDATE><SERIALNUMBER>SN-000123</SERIALNUMBER><ERROR></ERROR><ERRORMSG></ERRORMSG></ITEM></SETDFSTATUS>]]></XML>
      <!-- <CreateInvoices>Y</CreateInvoices> -->
      <!-- <SupplNr>L042</SupplNr> -->
      <!-- <Secret>K7x9Pq2mZ4</Secret> -->
    </ns1:pixiDFSetStatus>
  </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 = [
    'XML' => '<SETDFSTATUS><ITEM><ORDERHISTORYKEY>784512</ORDERHISTORYKEY><STATUS>FUS</STATUS><QTY>2</QTY><SHIPDATE>2024-05-14T10:30:00</SHIPDATE><TRACKINGID>00340434161094042557</TRACKINGID><INVOICENREXTERNAL>RE-2024-0815</INVOICENREXTERNAL><BATCHNUMBER>B2024-17</BATCHNUMBER><BESTBEFOREDATE>2025-12-31</BESTBEFOREDATE><SERIALNUMBER>SN-000123</SERIALNUMBER><ERROR></ERROR><ERRORMSG></ERRORMSG></ITEM></SETDFSTATUS>',
    // 'CreateInvoices' => 'Y',
    // 'SupplNr' => 'L042',
    // 'Secret' => 'K7x9Pq2mZ4',
];

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

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

pixiDFCreateInvoices

Verwendete Tabellen

Suppliers · Lesen Settings · Lesen OrderHistory · Lesen Orderlines · Schreiben TagMatch · Lesen OrderStates · Lesen LogTable · Schreiben

SQL-Objekt:: dbo.pipiDFSetStatus