Direct-Fulfillment Schreiben

pixiDFUpdateOrderlineStatus

Setzt den Direct-Fulfillment-Status einer Auftragsposition für einen authentifizierten Lieferanten, optional mit Versanddatum, Tracking-ID, Rechnungsnummer, Teilmenge und Chargendaten.

API-Aufruf, mit dem Direct-Fulfillment-Lieferanten den Bearbeitungsstand einer Auftragsposition an Pixi zurückmelden.

1. Authentifizierung

Der Lieferant wird in Suppliers über SupplNr gesucht; Secret muss der CustNr des Lieferanten entsprechen, der Lieferant darf nicht deaktiviert sein und muss CanDoDirectFulfillment = 1 haben.
Wird kein Lieferant gefunden und ist die Einstellung DFAPIAllowFullAccessWithoutSecret gleich 0 (oder nicht vorhanden), wird eine Zeile mit Error = '403' geliefert und nichts geändert.
Ist diese Einstellung ungleich 0, läuft der Aufruf auch mit falschem Secret weiter.

2. Ermitteln der Auftragsposition

Ist OrderlineRef kleiner als 1 (Standard), wird der Positionsschlüssel über OrderHistoryKey aus OrderHistory gelesen.
Leere Zeichenketten in BatchNumber, BestBeforeDate und SerialNumber werden als NULL behandelt.

3. Prüfungen (in der internen Prozedur Pixi_UpdateOrderlineDFStatusByOrderlineKey). Die Aktualisierung wird abgelehnt, wenn:

die Auftragsposition nicht existiert;
die Einstellung DFRequiredDataForSystemTags aktiv ist und der Artikel das System-Tag für Chargennummer (Tag -6) und/oder Mindesthaltbarkeitsdatum (Tag -7) trägt, der entsprechende Wert aber fehlt;
Qty kleiner als 1 oder größer als die aktuelle Positionsmenge ist;
die Position bereits den Status FUS oder einen in OrderStates als final markierten Status hat.

4. Aktualisierung

Ist Qty kleiner als die aktuelle Menge, wird die Position zuerst geteilt: Die ursprüngliche Position behält Qty, eine neue Position mit der Restmenge wird mit dem alten Status angelegt.
Der neue Status ergibt sich aus Status: STO und NLB werden unverändert übernommen; jeder andere Wert führt bei DF-Typ 1, 3 oder ohne DF-Typ zu FUS, sonst zu BES.
Die Position erhält den neuen Status, DFShipDate, DFShipmentTrackingID (aus DFTrackingID), InvoiceNrExternal, Chargennummer, Mindesthaltbarkeitsdatum, Seriennummer, UpdateDate und UpdateEmp = 'DF API'.
Ist der resultierende Status BES, wird eine Reservierung für den gesamten Auftrag angelegt.

5. Antwort Eine Zeile mit Error (200 oder 500) und ErrorMsg. 500 wird geliefert, wenn die Meldung das Wort error enthält. Bei Erfolg ist ErrorMsg leer oder enthält die Info zur Teilung. Jeder Aufruf nach erfolgreicher Authentifizierung schreibt eine Zeile in LogTable.

Hinweise

Der Aufruf prüft nicht, ob die Auftragsposition zum authentifizierten Lieferanten gehört; jeder Positionsschlüssel kann angesprochen werden.
DFShipDate, DFTrackingID und InvoiceNrExternal werden immer geschrieben; fehlen sie, werden vorhandene Werte mit NULL überschrieben. BatchNumber, BestBeforeDate und SerialNumber behalten ihre bisherigen Werte, wenn sie nicht übergeben werden.
Prüfmeldungen überschreiben sich gegenseitig; gemeldet wird nur die zuletzt fehlgeschlagene Prüfung.
Die Fehlererkennung basiert auf CHARINDEX('error', ErrorMsg); für die großgeschriebenen ERROR:-Meldungen funktioniert das nur bei einer nicht case-sensitiven Datenbank-Collation.
Laufzeitfehler während der Aktualisierung werden abgefangen, zurückgerollt und über log.InsertError protokolliert, ändern aber ErrorMsg nicht; die Antwort kann daher 200 mit leerer oder INFO-Meldung sein, obwohl nichts gespeichert wurde. Im Zweifel die Position anschließend prüfen.
Die Prüfung auf eine fehlgeschlagene Reservierung (ERROR: Error Creating Reservation) liest @@ERROR nach einer SET-Anweisung und greift daher praktisch nie.
Die Verarbeitung läuft in einer eigenen Transaktion bzw. einem Savepoint innerhalb einer bestehenden Transaktion. Lesezugriffe verwenden NOLOCK.
Das Verhalten von GOSBreakOrderline, Pixi_Res_CreateReservationForOrder, dbo.SettingGet und log.InsertError ist hier nicht sichtbar; diese können weitere Tabellen schreiben.
Ein Mindesthaltbarkeitsdatum 1900-01-01 wird wegen des Vergleichs mit '' wie ein leerer Wert behandelt.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`SupplNr` Pflicht	varchar(4) string	–	Lieferantennummer des Direct-Fulfillment-Lieferanten. Beispiel: `L001`
`Secret` Pflicht	varchar(20) string	–	Secret des Lieferanten; muss der beim Lieferanten hinterlegten `CustNr` entsprechen. Beispiel: `K4711`
`Status` Pflicht	varchar(3) string	–	Gewünschter Status. `STO` und `NLB` werden unverändert gesetzt; jeder andere Wert setzt `FUS` (DF-Typ 1, 3 oder keiner) bzw. `BES` (andere DF-Typen). Erlaubte Werte `STO` – Position erhält den Status `STO` (typischerweise Storno). `NLB` – Position erhält den Status `NLB` (typischerweise nicht lieferbar). `FUS` – Jeder andere Wert: Status wird `FUS` bei DF-Typ 1, 3 oder ohne DF-Typ, sonst `BES` mit Reservierung des Auftrags. Beispiel: `FUS`
`OrderHistoryKey`	int	0	Schlüssel des `OrderHistory`-Eintrags; dient zur Ermittlung der Position, wenn `OrderlineRef` nicht angegeben ist. Beispiel: `123456`
`DFShipDate`	datetime dateTime	NULL	Vom Lieferanten gemeldetes Versanddatum; wird in `DFShipDate` gespeichert (bei Weglassen mit NULL überschrieben). Beispiel: `2024-05-14T10:30:00`
`DFTrackingID`	varchar(100) string	NULL	Sendungsverfolgungsnummer; wird in `DFShipmentTrackingID` gespeichert (bei Weglassen mit NULL überschrieben). Beispiel: `00340434161234567890`
`Qty`	int	NULL	Bearbeitete Menge. Muss zwischen 1 und der aktuellen Positionsmenge liegen; ein kleinerer Wert teilt die Position. NULL behält die volle Menge. Beispiel: `2`
`InvoiceNrExternal`	varchar(20) string	NULL	Rechnungsnummer des Lieferanten; wird in `InvoiceNrExternal` gespeichert (bei Weglassen mit NULL überschrieben). Beispiel: `RE-2024-0815`
`OrderlineRef`	int	0	Schlüssel der Auftragsposition (`OrderlineKey`). Ist er kleiner als 1, wird er über `OrderHistoryKey` ermittelt. Beispiel: `987654`
`BatchNumber`	varchar(50) string	NULL	Chargennummer. Pflicht, wenn der Artikel das Chargen-System-Tag trägt und `DFRequiredDataForSystemTags` aktiv ist; bei Weglassen bleibt der bisherige Wert erhalten. Beispiel: `CH-2024-17`
`BestBeforeDate`	datetime dateTime	NULL	Mindesthaltbarkeitsdatum. Pflicht, wenn der Artikel das MHD-System-Tag trägt und `DFRequiredDataForSystemTags` aktiv ist; bei Weglassen bleibt der bisherige Wert erhalten. Beispiel: `2025-12-31T00:00:00`
`SerialNumber`	varchar(50) string	NULL	Seriennummer; wird in `SerialNr` gespeichert. Bei Weglassen bleibt der bisherige Wert erhalten. Beispiel: `SN123456789`

Antwort

Result-Set 1 · Immer; genau eine Zeile (entweder die 403-Autorisierungszeile oder das Ergebnis der Aktualisierung).

Statuszeile des Aufrufs.

Spalte	Typ	Beschreibung
`Error`	varchar(3) string	`200` = OK, `403` = nicht autorisiert, `500` = Prüf- oder Verarbeitungsfehler (Meldung enthält `error`).
`ErrorMsg` Kann leer sein	varchar(200) string	Fehlermeldung, Info zur Teilung (`INFO: Split Orderline ...`) oder leer bei einfachem Erfolg.

Beispielantwort

<SqlRowSet1>
  <row>
    <Error>200</Error>
    <ErrorMsg>INFO: Split Orderline - Updated Qty: 2, New Orderline Qty:1</ErrorMsg>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
403	Not Authorized. Secret or SupplNr is incorrect.	Kein aktiver Lieferant mit Direct Fulfillment passt zu `SupplNr` und `Secret`, und `DFAPIAllowFullAccessWithoutSecret` ist `0`. Lieferantennummer, Secret und DF-Kennzeichen des Lieferanten prüfen.
500	ERROR: Orderline not existing	Für `OrderlineRef` bzw. die über `OrderHistoryKey` referenzierte Position wurde keine Auftragsposition gefunden.
500	ERROR: Batch number and Best Before Date are required for the item Id {ItemId}	`DFRequiredDataForSystemTags` ist aktiv, der Artikel trägt beide System-Tags für Charge und MHD, und weder `BatchNumber` noch `BestBeforeDate` wurde übergeben.
500	ERROR: Best Before Date is required for the item Id {ItemId}	`DFRequiredDataForSystemTags` ist aktiv, der Artikel trägt das MHD-System-Tag und `BestBeforeDate` fehlt.
500	ERROR: Batch number is required for the item Id {ItemId}	`DFRequiredDataForSystemTags` ist aktiv, der Artikel trägt das Chargen-System-Tag und `BatchNumber` fehlt.
500	ERROR: Only positive values bigger than 1 are allowed! Sent value is {Qty}	`Qty` ist kleiner als 1. Eine positive Menge senden oder den Parameter weglassen.
500	ERROR: Value {Qty} is too big, MAX value allowed:{OriginalQty}	`Qty` ist größer als die aktuelle Menge der Position. Die Meldung beginnt mit einem Leerzeichen.
500	ERROR: Orderline was already processed.	Die Position hat bereits den Status `FUS` oder einen laut `OrderStates` finalen Status und kann nicht erneut aktualisiert werden.

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:pixiDFUpdateOrderlineStatus>
      <SupplNr>L001</SupplNr>
      <Secret>K4711</Secret>
      <Status>FUS</Status>
      <!-- <OrderHistoryKey>123456</OrderHistoryKey> -->
      <!-- <DFShipDate>2024-05-14T10:30:00</DFShipDate> -->
      <!-- <DFTrackingID>00340434161234567890</DFTrackingID> -->
      <!-- <Qty>2</Qty> -->
      <!-- <InvoiceNrExternal>RE-2024-0815</InvoiceNrExternal> -->
      <!-- <OrderlineRef>987654</OrderlineRef> -->
      <!-- <BatchNumber>CH-2024-17</BatchNumber> -->
      <!-- <BestBeforeDate>2025-12-31T00:00:00</BestBeforeDate> -->
      <!-- <SerialNumber>SN123456789</SerialNumber> -->
    </ns1:pixiDFUpdateOrderlineStatus>
  </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:pixiDFUpdateOrderlineStatus>
      <SupplNr>L001</SupplNr>
      <Secret>K4711</Secret>
      <Status>FUS</Status>
      <!-- <OrderHistoryKey>123456</OrderHistoryKey> -->
      <!-- <DFShipDate>2024-05-14T10:30:00</DFShipDate> -->
      <!-- <DFTrackingID>00340434161234567890</DFTrackingID> -->
      <!-- <Qty>2</Qty> -->
      <!-- <InvoiceNrExternal>RE-2024-0815</InvoiceNrExternal> -->
      <!-- <OrderlineRef>987654</OrderlineRef> -->
      <!-- <BatchNumber>CH-2024-17</BatchNumber> -->
      <!-- <BestBeforeDate>2025-12-31T00:00:00</BestBeforeDate> -->
      <!-- <SerialNumber>SN123456789</SerialNumber> -->
    </ns1:pixiDFUpdateOrderlineStatus>
  </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 = [
    'SupplNr' => 'L001',
    'Secret' => 'K4711',
    'Status' => 'FUS',
    // 'OrderHistoryKey' => '123456',
    // 'DFShipDate' => '2024-05-14T10:30:00',
    // 'DFTrackingID' => '00340434161234567890',
    // 'Qty' => '2',
    // 'InvoiceNrExternal' => 'RE-2024-0815',
    // 'OrderlineRef' => '987654',
    // 'BatchNumber' => 'CH-2024-17',
    // 'BestBeforeDate' => '2025-12-31T00:00:00',
    // 'SerialNumber' => 'SN123456789',
];

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

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

Verwendete Tabellen

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

SQL-Objekt:: dbo.pipiDFUpdateOrderlineStatus