Orders Schreiben

pixiCreateOrderComment

Legt einen Freitext-Kommentar zu einem bestehenden Auftrag an und speichert Benutzer und Erstellungszeitpunkt.

Legt einen neuen Eintrag in den Auftragskommentaren für den angegebenen Auftrag an.

Ablauf:

Prüfung: Fehlt OrderNr oder ist sie 0, oder fehlt Comment bzw. ist er leer, liefert der Aufruf eine Fehlerzeile und bricht ab.
Auftragsprüfung: Der Aufruf zählt die Aufträge in OrderHeader mit der angegebenen OrderNr. Existiert keiner, wird eine Fehlerzeile mit der Auftragsnummer geliefert.
Anlage: Andernfalls wird eine Zeile in OrderComments eingefügt, mit Auftragsnummer, Kommentartext, dem Wert von User als anlegendem Mitarbeiter (CreateEmp) und der aktuellen Serverzeit als CreateDate.
Anschließend wird eine einzelne Zeile mit ReturnCode = SUCCESS geliefert.

Jeder Aufruf legt einen neuen Kommentar an. Bestehende Kommentare werden nie geändert oder ersetzt.

Hinweise

Der Kopfkommentar im Code besagt, dass die Prozedur Auftragskommentare liest; das ist falsch. Die Prozedur legt ausschließlich einen Kommentar an.
Die Ergebniszeile hat unterschiedliche Formen: Fehlerzeilen enthalten die Spalten ReturnCode und ErrorMsg, die Erfolgszeile nur ReturnCode. Clients sollten zuerst ReturnCode auswerten.
Es wird keine explizite Transaktion verwendet. Ein erneuter Aufruf legt einen doppelten Kommentar an; Wiederholungen nach Timeouts können daher zu Doppeleinträgen führen.
CreateDate wird mit CURRENT_TIMESTAMP gesetzt, also mit der lokalen Zeit des Datenbankservers.
Comment ist varchar, nicht nvarchar; Zeichen außerhalb der Codepage der Datenbank können verloren gehen.
Da SQL Server nachfolgende Leerzeichen beim Stringvergleich ignoriert, wird ein Kommentar, der nur aus Leerzeichen besteht, als leer abgewiesen.
Werte für User mit mehr als 50 Zeichen werden durch den Parametertyp abgeschnitten.
Der Auftrag wird ausschließlich über die interne OrderNr identifiziert; eine externe Auftragsnummer wird nicht unterstützt.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`OrderNr`	int	NULL	Interne Pixi-Auftragsnummer (`OrderHeader.OrderNr`), zu der der Kommentar angelegt wird. Muss gesetzt und ungleich `0` sein, sonst wird eine Fehlerzeile geliefert. Beispiel: `104523`
`Comment`	varchar(max) string	NULL	Text des Kommentars. Darf nicht leer sein, sonst wird eine Fehlerzeile geliefert. Beispiel: `Customer requested delivery after 2 pm.`
`User`	varchar(50) string	API	Name oder Kürzel des Benutzers, der als Ersteller des Kommentars (`CreateEmp`) gespeichert wird. Beispiel: `SHOP`

Antwort

Result-Set 1 · Wenn `OrderNr` fehlt/0 ist oder `Comment` leer ist, oder wenn kein Auftrag mit `OrderNr` existiert.

Fehlerzeile; es wird kein Kommentar angelegt.

Spalte	Typ	Beschreibung
`ReturnCode`	varchar(5) string	Immer `ERROR`.
`ErrorMsg`	varchar(max) string	Fehlertext mit der Beschreibung des Problems.

Result-Set 2 · Bei Erfolg, nachdem der Kommentar eingefügt wurde.

Erfolgszeile.

Spalte	Typ	Beschreibung
`ReturnCode`	varchar(7) string	Immer `SUCCESS`.

Beispielantwort

<SqlRowSet1>
  <row>
    <ReturnCode>SUCCESS</ReturnCode>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
ERROR	Please provide an order number and a comment	`OrderNr` fehlt oder ist `0`, oder `Comment` fehlt bzw. ist leer. Eine gültige Auftragsnummer und einen nicht leeren Kommentar übergeben.
ERROR	Couldnt find an order with order number {OrderNr}	In `OrderHeader` existiert keine Zeile mit der angegebenen `OrderNr`. Prüfen, ob die interne Pixi-Auftragsnummer (nicht die externe Shop-Auftragsnummer) verwendet wird.

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:pixiCreateOrderComment>
      <!-- <OrderNr>104523</OrderNr> -->
      <!-- <Comment>Customer requested delivery after 2 pm.</Comment> -->
      <!-- <User>SHOP</User> -->
    </ns1:pixiCreateOrderComment>
  </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:pixiCreateOrderComment>
      <!-- <OrderNr>104523</OrderNr> -->
      <!-- <Comment>Customer requested delivery after 2 pm.</Comment> -->
      <!-- <User>SHOP</User> -->
    </ns1:pixiCreateOrderComment>
  </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 = [
    // 'OrderNr' => '104523',
    // 'Comment' => 'Customer requested delivery after 2 pm.',
    // 'User' => 'SHOP',
];

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

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

Verwendete Tabellen

OrderHeader · Lesen OrderComments · Schreiben

SQL-Objekt:: dbo.pipiCreateOrderComment