Shipping Schreiben

pixiUpdateInvoicePackage

Aktualisiert Tracking-IDs, Label-URLs und Providermeldungen eines Rechnungspakets und überträgt die Tracking-IDs auf die zugehörige Rechnung.

Schreibt das Ergebnis eines Versanddienstleisters (Trackingnummer, Label-URLs, Providermeldungen) in ein Paket einer Rechnung (pixi.InvoicePackage) und in die Rechnung selbst (dbo.Invoices).

Ablauf:

Alle als Leerstring übergebenen Textparameter werden als NULL (= nicht übergeben) behandelt.
Das Paket PackageId muss existieren, andernfalls wird eine 400-Antwort geliefert.
Wird InvoiceKey übergeben, muss er zur Rechnung des Pakets passen, andernfalls wird eine 400-Antwort geliefert. Ohne Angabe wird die Rechnung des Pakets verwendet.
Paket-Update: TrackingID, ReturnTrackingId, ExternalShipmentId, MessageFromProvider und MessageFromProviderDetail werden nur mit übergebenen Werten überschrieben; nicht übergebene Werte bleiben erhalten. ShippingLabelUrl und ReturnLabelUrl erhalten den neuen Wert oder behalten den aktuellen. Bei Paketen eines Versanddienstleisters mit External-Label-Funktionalität (Funktionalitätsversion 3), die über eine Toolbox-Station versendet wurden, wird ShippingLabelUrl auf NO URL FROM PROVIDER gesetzt, wenn überhaupt keine URL vorhanden ist. RecordModifiedOn und RecordModifiedByUserId (Benutzer API) werden gesetzt.
Rechnungs-Update:
- ShipmentTrackingID: ist das Feld leer, wird es auf TrackingId gesetzt; sonst wird TrackingId mit ; angehängt, sofern der vorhandene Wert sie noch nicht enthält.
- retTrackID / retTrackIDhist: ist retTrackID leer, wird retTrackID auf ReturnTrackingId und die Historie auf ReturnTrackingId; gesetzt. Andernfalls wird die neue ID, falls noch nicht in retTrackID enthalten, an die Historie angehängt und retTrackID ersetzt.
- UpdateDate und UpdateEmp (TrackingID API Import) werden gesetzt.
Bei ResetClientNotifiedFlag = 1 wird der jeweils letzte AUS-Eintrag (ausgeliefert) der Auftragshistorie jeder Auftragsposition der Rechnung auf ClientNotified = 'N' zurückgesetzt, damit der Auftrag erneut mit Tracking-ID exportiert wird.
Eine Zeile mit Response = 200 OK wird geliefert und die Transaktion festgeschrieben.
Nach dem Commit werden MQ-Events veröffentlicht: PackageLabelSaved (nur bei External-Label-Paketen mit Toolbox-Station, mit Kennzeichen, ob sich Versand- oder Retouren-Label-URL geändert hat) und immer InvoiceChanged mit Parameter SetTrackingId.

Hinweise

Läuft in einer eigenen Transaktion (bzw. einem Savepoint, falls bereits eine Transaktion offen ist). Ein exklusiver Application Lock PixiInvoicePackage (Timeout 30 s) serialisiert den Aufruf mit anderen Paket-Updates; kann der Lock nicht erlangt werden, wird das Update trotzdem ausgeführt.
Deadlocks (Fehler 1205) werden bis zu 5-mal mit 5 ms Verzögerung wiederholt. Andere Fehler werden über log.InsertError protokolliert und mit 500 Internal Server Error beantwortet. In seltenen Fehlersituationen nach der 200 OK-Zeile (z. B. beim Commit oder Event-Versand) kann mehr als ein Response-Resultset geliefert werden.
Die Duplikatprüfung der Tracking-IDs ist ein Teilstring-Vergleich per LIKE: Eine ID, die Teil einer vorhandenen ID ist (z. B. 123 in 12345), wird nicht an die Rechnung angehängt; % oder _ in IDs wirken als Platzhalter.
InvoicePackage.TrackingID wird überschrieben, während Invoices.ShipmentTrackingID alle IDs mit ; getrennt sammelt.
Hat die Rechnung noch keine Retouren-Tracking-ID, wird retTrackIDhist durch die neue ID ersetzt (nicht ergänzt).
Während des Rechnungs-Updates wird CONTEXT_INFO auf 0x11111 gesetzt, vermutlich um Trigger auf dbo.Invoices zu beeinflussen.
Lesezugriffe erfolgen mit NOLOCK.
MQ-Events werden nur gesendet, wenn die Einstellung pixiMQ_Enabled aktiv ist und die Events in EventConfiguration konfiguriert und aktiviert sind.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`PackageId` Pflicht	int	–	ID des Rechnungspakets (`pixi.InvoicePackage.Id`), das aktualisiert wird. Beispiel: `48211`
`InvoiceKey`	int	NULL	Optionaler Rechnungsschlüssel zur Prüfung. Wird er übergeben, muss er zur Rechnung des Pakets passen; ohne Angabe wird die Rechnung des Pakets verwendet. Beispiel: `1023456`
`ShippingLabelUrl`	varchar(8000) string	NULL	URL des Versandlabels. Leer oder nicht übergeben behält die aktuelle URL. Beispiel: `https://labels.example-carrier.com/label/00340434161094042557.pdf`
`TrackingId`	varchar(512) string	NULL	Trackingnummer der Sendung. Überschreibt die Tracking-ID des Pakets und wird an `Invoices.ShipmentTrackingID` angehängt, falls noch nicht enthalten. Beispiel: `00340434161094042557`
`ReturnLabelUrl`	varchar(8000) string	NULL	URL des Retourenlabels. Leer oder nicht übergeben behält die aktuelle URL. Beispiel: `https://labels.example-carrier.com/return/00340434161094042564.pdf`
`ReturnTrackingId`	varchar(512) string	NULL	Trackingnummer des Retourenlabels. Wird in das Paket sowie in `Invoices.retTrackID` / `retTrackIDhist` geschrieben. Beispiel: `00340434161094042564`
`ExternalShipmentId`	varchar(512) string	NULL	Sendungs-ID beim Versanddienstleister. Wird nur überschrieben, wenn übergeben. Beispiel: `SHP-2024-778812`
`MessageFromProvider`	varchar(max) string	NULL	Meldung des Versanddienstleisters. Wird nur überschrieben, wenn übergeben. Beispiel: `Label created successfully`
`MessageFromProviderDetail`	varchar(max) string	NULL	Detailmeldung des Versanddienstleisters. Wird nur überschrieben, wenn übergeben. Beispiel: `Weight 2.4 kg, product: Paket National`
`ResetClientNotifiedFlag`	bit boolean	0	Bei 1 werden die letzten `AUS`-Einträge der Auftragshistorie der Auftragspositionen der Rechnung auf `ClientNotified = 'N'` gesetzt, damit der Versand erneut mit Tracking-ID exportiert wird. Erlaubte Werte `0` – Auftragshistorie nicht ändern. `1` – Benachrichtigungskennzeichen zurücksetzen, damit der Versand erneut exportiert wird. Beispiel: `1`

Antwort

Result-Set 1 · Immer (eine Zeile mit dem Ergebnis des Aufrufs).

HTTP-ähnlicher Statustext des Aufrufs.

Spalte	Typ	Beschreibung
`Response`	varchar(100) string	`200 OK` bei Erfolg, sonst eine `400`- oder `500`-Meldung.

Beispielantwort

<SqlRowSet1>
  <row>
    <Response>200 OK</Response>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
400	400 Bad Request - Package ID does not exist.	Es existiert kein Rechnungspaket mit der übergebenen `PackageId`. Paket-ID prüfen.
400	400 Bad Request - Invoice ID does not match the package.	Der übergebene `InvoiceKey` weicht von der Rechnung des Pakets ab. Korrekten Schlüssel übergeben oder Parameter weglassen.
500	500 Internal Server Error	Beim Update ist ein unerwarteter SQL-Fehler aufgetreten (oder ein Deadlock bestand auch nach 5 Wiederholungen). Die Änderungen werden zurückgerollt und der Fehler protokolliert.

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:pixiUpdateInvoicePackage>
      <PackageId>48211</PackageId>
      <!-- <InvoiceKey>1023456</InvoiceKey> -->
      <!-- <ShippingLabelUrl>https://labels.example-carrier.com/label/00340434161094042557.pdf</ShippingLabelUrl> -->
      <!-- <TrackingId>00340434161094042557</TrackingId> -->
      <!-- <ReturnLabelUrl>https://labels.example-carrier.com/return/00340434161094042564.pdf</ReturnLabelUrl> -->
      <!-- <ReturnTrackingId>00340434161094042564</ReturnTrackingId> -->
      <!-- <ExternalShipmentId>SHP-2024-778812</ExternalShipmentId> -->
      <!-- <MessageFromProvider>Label created successfully</MessageFromProvider> -->
      <!-- <MessageFromProviderDetail>Weight 2.4 kg, product: Paket National</MessageFromProviderDetail> -->
      <!-- <ResetClientNotifiedFlag>1</ResetClientNotifiedFlag> -->
    </ns1:pixiUpdateInvoicePackage>
  </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:pixiUpdateInvoicePackage>
      <PackageId>48211</PackageId>
      <!-- <InvoiceKey>1023456</InvoiceKey> -->
      <!-- <ShippingLabelUrl>https://labels.example-carrier.com/label/00340434161094042557.pdf</ShippingLabelUrl> -->
      <!-- <TrackingId>00340434161094042557</TrackingId> -->
      <!-- <ReturnLabelUrl>https://labels.example-carrier.com/return/00340434161094042564.pdf</ReturnLabelUrl> -->
      <!-- <ReturnTrackingId>00340434161094042564</ReturnTrackingId> -->
      <!-- <ExternalShipmentId>SHP-2024-778812</ExternalShipmentId> -->
      <!-- <MessageFromProvider>Label created successfully</MessageFromProvider> -->
      <!-- <MessageFromProviderDetail>Weight 2.4 kg, product: Paket National</MessageFromProviderDetail> -->
      <!-- <ResetClientNotifiedFlag>1</ResetClientNotifiedFlag> -->
    </ns1:pixiUpdateInvoicePackage>
  </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 = [
    'PackageId' => '48211',
    // 'InvoiceKey' => '1023456',
    // 'ShippingLabelUrl' => 'https://labels.example-carrier.com/label/00340434161094042557.pdf',
    // 'TrackingId' => '00340434161094042557',
    // 'ReturnLabelUrl' => 'https://labels.example-carrier.com/return/00340434161094042564.pdf',
    // 'ReturnTrackingId' => '00340434161094042564',
    // 'ExternalShipmentId' => 'SHP-2024-778812',
    // 'MessageFromProvider' => 'Label created successfully',
    // 'MessageFromProviderDetail' => 'Weight 2.4 kg, product: Paket National',
    // 'ResetClientNotifiedFlag' => '1',
];

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

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

Verwendete Tabellen

InvoicePackage · Schreiben ShipVendor · Lesen ShipVendorFunctionality · Lesen Invoices · Schreiben OrderHistory · Schreiben Invlines · Lesen UCS_USERS · Lesen

SQL-Objekt:: dbo.pipiUpdateInvoicePackage