Orders Schreiben

pixiUpdateOrder

Aktualisiert Versandkosten, Versanddatum, Shop-Notiz, Gutschein, Adressbemerkung und Zahlungsart eines bestehenden offenen Auftrags.

Aktualisiert ausgewählte Kopfdaten eines bestehenden Auftrags. Der Auftrag wird über OrderNr oder OrderNrExternal gefunden.

Prüfungen (jede liefert eine Error-Zeile und bricht ab):

Mindestens OrderNr oder OrderNrExternal muss angegeben sein.
Der Auftrag wird mit OrderNr = @OrderNr OR OrderNrExternal = @OrderNrExternal gesucht (erster Treffer). Wird keiner gefunden, kommt ein Fehler.
VoucherID und VoucherAmount müssen gemeinsam angegeben werden.
Der Gutschein darf nicht bereits auf Auftragspositionen eines anderen Auftrags verwendet sein.
Ist PaymentType angegeben, muss der Wert als Code in der Tabelle Payments existieren.
Der Auftrag muss noch änderbar sein: Der aus den Auftragspositionen berechnete Gesamtstatus muss OPEN oder HOLD sein. Zusätzlich muss die Anzahl nicht finaler Positionen mit Rechnungspositionen kleiner sein als die Anzahl der Positionen, die weder final sind noch den Status MIN oder FUS haben.

Aktualisierung:

Nicht übergebene Parameter behalten die aktuellen Werte des Auftrags.
ShipCosts wird bei B2B-Aufträgen auf die Netto-Versandkosten angewendet, bei B2C-Aufträgen auf die Brutto-Versandkosten.
ShipDate ersetzt das Versanddatum. Der Wert 1900-01-01 setzt es auf NULL.
ShopNote und AddressRemarks ersetzen die gespeicherten Texte.
Alle übrigen Kopffelder werden unverändert durchgereicht, z. B. Geschenktext, Versandanweisung, Versanddienstleister, CCP-Merchant, ccpPayID, Verfahren/Product/Extras und Auftragstyp.
Die eigentliche Aktualisierung erfolgt über die interne Prozedur Pixi_UpdateOrder. Sie setzt UpdateDate auf die aktuelle Zeit.
Ändern sich die Versandkosten und gilt weder Gutschein noch Rabatt, wird auch ShipCost der Auftragspositionen angepasst.
Ein angegebener Gutschein wird in Voucher angelegt, falls er noch nicht existiert. Andernfalls wird sein Betrag aktualisiert. Die Gutschein-ID wird danach auf alle Auftragspositionen geschrieben.
Ist PaymentType angegeben, wird der Wert in APayment der Adresse des Auftrags (AddrRef) geschrieben.

Bei Erfolg wird eine Success-Zeile geliefert.

Hinweise

VoucherAmount wird über NULLIF(@VoucherAmount, '') geprüft. Da '' bei money zu 0 konvertiert wird, gilt ein Betrag von 0 als nicht angegeben. VoucherID mit Betrag 0 liefert daher VoucherID provided without VoucherAmount.
Eine leere VoucherID gilt als nicht angegeben.
Sind OrderNr und OrderNrExternal angegeben und passen sie zu verschiedenen Aufträgen, wird ein beliebiger davon aktualisiert (TOP (1) ohne ORDER BY).
Bei der Meldung does not exist wird der Text per Verkettung gebildet. Ist einer der beiden Bezeichner NULL, ist die Spalte Message NULL.
Pixi_UpdateOrder läuft in einer eigenen Transaktion und fängt Fehler selbst ab. Sie protokolliert sie über log.InsertError und wirft sie nicht erneut, sodass die äußere Fehlerbehandlung sie ggf. nicht sieht. Eine Success-Zeile ist daher auch möglich, wenn die innere Aktualisierung zurückgerollt wurde. log.InsertError liegt nicht vor.
Die Aktualisierung der Zahlungsart in Addresses erfolgt nach der inneren Transaktion und außerhalb davon.
Hat der Auftrag keinen CCP-Merchant, kann die innere Prozedur anhand der Einstellung DefaultCCPMerchant einen setzen.
Ist ccpPayID bei einem offenen Auftrag NULL, wird ein Leerstring gespeichert.
ShopNote ist als varchar(max) deklariert. Zeichen außerhalb der Codepage der Datenbank gehen verloren, obwohl die Zielspalte nvarchar ist.
Lesezugriffe im Prüfteil nutzen NOLOCK; die innere Prozedur setzt UPDLOCK auf OrderHeader und Orderlines.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`OrderNr`	int	NULL	Pixi-Auftragsnummer. Entweder diese oder `OrderNrExternal` ist erforderlich. Beispiel: `100234`
`OrderNrExternal`	varchar(50) string	NULL	Externe Auftragsnummer (Shop). Wird verwendet, wenn `OrderNr` fehlt; Leerstring gilt als nicht angegeben. Beispiel: `SHOP-2024-001234`
`ShipCosts`	money decimal	NULL	Neue Versandkosten (netto bei `B2B`-, brutto bei `B2C`-Aufträgen). Ohne Angabe bleibt der aktuelle Wert. Beispiel: `4.95`
`ShipDate`	datetime dateTime	NULL	Neues Versanddatum. Ohne Angabe bleibt der aktuelle Wert; `1900-01-01` löscht es. Beispiel: `2024-05-20T00:00:00`
`ShopNote`	varchar(max) string	NULL	Notiz des Shops zum Auftrag (Shop-Kommentar). Ohne Angabe bleibt die aktuelle Notiz. Beispiel: `Bitte vor 12 Uhr liefern`
`VoucherID`	varchar(50) string	NULL	Gutschein-ID. Muss zusammen mit `VoucherAmount` angegeben werden und darf nicht in einem anderen Auftrag verwendet sein. Beispiel: `SUMMER10`
`VoucherAmount`	money decimal	NULL	Durch den Gutschein abgedeckter Betrag. Erfordert `VoucherID`; `0` gilt als nicht angegeben. Beispiel: `10.00`
`PaymentType`	varchar(1) string	NULL	Zahlungsart-Code; muss in `Payments` existieren. Wird in `APayment` der Auftragsadresse geschrieben. Leerstring gilt als nicht angegeben. Beispiel: `V`
`AddressRemarks`	varchar(255) string	NULL	Neue Adressbemerkung des Auftrags. Ohne Angabe bleibt der aktuelle Wert. Beispiel: `Hinterhaus, 2. OG`

Antwort

Result-Set 1 · Immer (eine Zeile, Erfolg oder Fehler)

Statuszeile mit dem Ergebnis des Aufrufs.

Spalte	Typ	Beschreibung
`Status`	varchar(7) string	`Success` oder `Error`.”
`Message` Kann leer sein	varchar(max) string	Ergebnis- oder Fehlertext.

Beispielantwort

<SqlRowSet1>
  <row>
    <Status>Success</Status>
    <Message>Order with OrderNr: 100234 was updated.</Message>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
Error	Parameter OrderNr/OrderNrExternal is mandatory parameter and needs to be provided.	Weder `OrderNr` noch ein nicht leeres `OrderNrExternal` wurde übergeben.
Error	Order with OrderNr: {OrderNr} ({OrderNrExternal}) does not exist.	Kein Auftrag passt zur angegebenen Nummer. Ist ein Bezeichner NULL, ist die Meldung selbst NULL.
Error	VoucherAmount provided without VoucherID.	`VoucherAmount` wurde angegeben, `VoucherID` fehlt oder ist leer.
Error	VoucherID provided without VoucherAmount.	`VoucherID` wurde ohne `VoucherAmount` (oder mit Betrag 0) angegeben.
Error	Voucher {VoucherID} already used in other orderlines.	Der Gutschein ist bereits Auftragspositionen eines anderen Auftrags zugeordnet.
Error	Payment type {PaymentType} does not exist.	Der angegebene Zahlungsart-Code existiert nicht in `Payments`.
Error	Order with OrderNr: {OrderNr} ({OrderNrExternal}) can not be updated anymore.	Der Auftrag ist nicht `OPEN`/`HOLD`, oder alle verbleibenden offenen Positionen sind bereits berechnet.
Error	Unexpected error: {ERROR_MESSAGE}	Bei der Aktualisierung ist ein unerwarteter SQL-Fehler aufgetreten.

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:pixiUpdateOrder>
      <!-- <OrderNr>100234</OrderNr> -->
      <!-- <OrderNrExternal>SHOP-2024-001234</OrderNrExternal> -->
      <!-- <ShipCosts>4.95</ShipCosts> -->
      <!-- <ShipDate>2024-05-20T00:00:00</ShipDate> -->
      <!-- <ShopNote>Bitte vor 12 Uhr liefern</ShopNote> -->
      <!-- <VoucherID>SUMMER10</VoucherID> -->
      <!-- <VoucherAmount>10.00</VoucherAmount> -->
      <!-- <PaymentType>V</PaymentType> -->
      <!-- <AddressRemarks>Hinterhaus, 2. OG</AddressRemarks> -->
    </ns1:pixiUpdateOrder>
  </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:pixiUpdateOrder>
      <!-- <OrderNr>100234</OrderNr> -->
      <!-- <OrderNrExternal>SHOP-2024-001234</OrderNrExternal> -->
      <!-- <ShipCosts>4.95</ShipCosts> -->
      <!-- <ShipDate>2024-05-20T00:00:00</ShipDate> -->
      <!-- <ShopNote>Bitte vor 12 Uhr liefern</ShopNote> -->
      <!-- <VoucherID>SUMMER10</VoucherID> -->
      <!-- <VoucherAmount>10.00</VoucherAmount> -->
      <!-- <PaymentType>V</PaymentType> -->
      <!-- <AddressRemarks>Hinterhaus, 2. OG</AddressRemarks> -->
    </ns1:pixiUpdateOrder>
  </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' => '100234',
    // 'OrderNrExternal' => 'SHOP-2024-001234',
    // 'ShipCosts' => '4.95',
    // 'ShipDate' => '2024-05-20T00:00:00',
    // 'ShopNote' => 'Bitte vor 12 Uhr liefern',
    // 'VoucherID' => 'SUMMER10',
    // 'VoucherAmount' => '10.00',
    // 'PaymentType' => 'V',
    // 'AddressRemarks' => 'Hinterhaus, 2. OG',
];

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

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

Verwendete Tabellen

Payments · Lesen OrderHeader · Schreiben Orderlines · Schreiben Invlines · Lesen OrderStates · Lesen Addresses · Schreiben Voucher · Schreiben Customers · Lesen Currency · Lesen

SQL-Objekt:: dbo.pipiUpdateOrder