Streamed Statuses bieten eine Möglichkeit, schnell über Statusänderungen deiner Sendungen informiert zu werden. Es ist nicht nötig, die Daten per getStatus-Aufruf abzurufen; wir liefern sie dir über einen Streaming-Push-Mechanismus. Du kannst Events abonnieren, und wenn ein Update erfolgt, senden wir Statusdaten an die URL, die du in MyTranssmart im Menü Manage account > Streamed Statuses angibst.
Der erste Schritt besteht darin, unseren Support zu kontaktieren, damit die Funktion für dich aktiviert wird. Wir aktivieren sie zunächst in unserer Accept-Umgebung, damit du die Integration konfigurieren und testen kannst. Wenn dies erfolgreich war, aktivieren wir sie in der Production-Umgebung.
Setup
Stelle zunächst sicher, dass du einen authentifizierten Endpoint hast, der Statusupdates empfangen kann.
Als Nächstes aktivierst du die Funktion und schließt die Konfiguration auf der Setup-Seite ab.
- URL = dein Endpoint
- Authentication = wähle zwischen None, Header oder Basic, je nach gewünschter Konfiguration.
- Status push method = wähle zwischen Package level (Standard) oder Shipment level. Siehe Erläuterung unten
Wichtiger Hinweis: (bitte lies auch das Update von Dezember 2024 unten)
Stelle in deinem Mapping sicher, dass du den Statuswert aus dem Feld genericStatusCode in den shipmentLines ausliest und nicht aus dem shipmentStatus im shipment header. Der Grund ist, dass wir für einige Carrier das Statusupdate nicht auf shipment-header-Ebene erhalten und wir per Algorithmus den Status auf shipment-header-Ebene nach der Prüfung des Status pro shipment line ändern.
Example:
Eine Sendung hat 3 Lines:
Line 1: Package mit Status DONE
Line 2: Package mit Status TRNS
Line 3: Package mit Status TRNS
Der shipment header status ist TRNS
Wir erhalten das Status-Update der Paketzeile 2, deren Status sich auf DONE ändert. Da sich in Zeile 3 jedoch noch ein Paket mit dem Status TRNS befindet, ändert der Algorithmus den Status des Shipment Headers nicht, sodass er TRNS bleibt.
Wir erhalten das Status-Update der Paketzeile 3, deren Status sich auf DONE ändert. Da es nun keine Pakete mit dem Status TRNS mehr gibt, ändert der Algorithmus den Status des Shipment Headers auf DONE. Zu dem Zeitpunkt, als wir dieses Status-Update erhalten, haben wir die Statusmeldung jedoch bereits an euren Endpoint gesendet. In diesem Moment war das Feld shipmentStatus im Header noch TRNS, während der genericStatusCode in der shipmentLine bereits den Status DONE hatte. Wenn ihr auf den Status des Shipment Headers abbilden würdet, bliebe die Sendung in eurem System auf TRNS, anstatt auf DONE zu wechseln. Daher ist es wichtig, auf den Statuswert aus dem Feld genericStatusCode in den shipmentLines abzubilden.
Update: Im Dezember 2024 haben wir eine Einstellung hinzugefügt, mit der festgelegt werden kann, ob die Nachricht, die wir pushen, durch die Paketzeilen oder den Shipment Header ausgelöst werden soll.
Die Standardeinstellung ist weiterhin pro Paketzeile. Wenn du dies auf Shipment Header umstellen möchtest, ändere die Einstellung entsprechend. Du musst dies tun, wenn du das Feld genericStatusCode in den shipmentLines nicht zuordnen kannst.
Die neue Einstellung ist auf der Konfigurationsseite unter Manage account > Streamed Statuses verfügbar.
Message format
Die Payload, die in der Statusbenachrichtigung gesendet wird, ist identisch mit der Response auf Status Retrieval Requests, Kapitel 5.1 unserer DevDocs: https://devdocs.transsmart.com/#_5_2_status_stream
isIncremental
Der Parameter isIncremental, der in den Status Retrieval API Endpoints verwendet wird, wird nicht von den Nachrichten beeinflusst, die von unserem System gepusht werden. Wenn du weiterhin Statusanfragen in dein eigenes System oder eventuell in ein zweites System pullen möchtest, ist das weiterhin möglich.
Sub accounts
Wenn du eine Konfiguration mit einem Hauptkonto und einem oder mehreren Sub Accounts hast, hängt es von der Endpoint-Konfiguration ab, wie dies eingerichtet werden muss. Wenn du einen einzigen Endpoint hast, über den du alle Statusmeldungen aller Konten erhalten möchtest, reicht es aus, ihn nur auf dem Hauptkonto zu konfigurieren. Die Einstellung wird automatisch von allen Sub Accounts übernommen.
Wenn du unterschiedliche Endpoints pro Sub Account hast, kannst du die Konfiguration für jeden Sub Account separat vornehmen.