In diesem Artikel geben wir Hinweise, wie Sie die API von Cargo Controller Export in Ihr eigenes System implementieren können. Stellen Sie sicher, dass Ihnen kein Mehrwert entgeht, indem Sie alle Datenpunkte in Ihrem System implementieren.
Verfügbare Webhook-Events
Im Artikel Webhook-Events der API für Cargo Controller Export sehen Sie eine Übersicht über alle verfügbaren Webhook-Events für den Dienst Cargo Controller Export. Die Webhook-Events sind an die logistischen Auswirkungen gekoppelt, sodass bestimmt werden kann, welche Datenpunkte für Ihre Organisation wertvoll sind.
Beachten Sie, dass jede Buchung, die von Ihrer Organisation verfolgt wird, zu Transaktionskosten führt – auch wenn sich später herausstellt, dass die Buchung nicht existiert. Beispiel für eine nicht existierende Buchung: Eine Buchung wird vorab bei der Schifffahrtsagentur angelegt, wird jedoch letztlich nicht ausgeführt.
Tracking von Exportladung
Cargo Controller Export arbeitet mit einer RESTful API und Webhook (HTTPS calls). Die Spezifikationen finden Sie hier.
In den Webhook-Updates senden wir den zuletzt bekannten Status (state) Ihrer Ladung. Darüber hinaus sendet Portbase auch die event payload mit – mit ausschließlich den Unterschieden gegenüber den letzten Informationen. Es liegt an Ihrer Organisation zu bestimmen, auf Basis welcher Logik die Informationen gespeichert werden: Unterschiede zwischen dem state oder die Verarbeitung der event payload.
In Cargo Controller Import wird nur state gesendet, nicht die event payload.
Schiffsinformationen wie ETA-, ETD-, ATA- und ATD- Schiff und cargo window (cargo opening and closing) werden Premium Terminal Data genannt. Mehr Informationen zu diesen Datenpunkten finden Sie hier.
Wenn Sie Zugriff auf diese Datenpunkte haben, können Sie die Buchung auch mit den Schiffsinformationen verknüpfen. Wenn die Schifffahrtsagentur die Ladeliste an Portbase sendet, können wir die Verknüpfung zwischen Buchungsnummer und Schiffsinformationen herstellen. Diese Verknüpfung können Sie auch auf anderen Wegen herstellen. Weiter unten in diesem Artikel finden Sie hierzu mehr.
Verfolgen Sie Ihre Exportladung
Es gibt 3 Möglichkeiten, eine Buchungsnummer zu verfolgen:
- API – mit oder ohne Schiffsinformationen
- Web interface
- Über Notification Export Documentation
API – mit oder ohne Schiffsinformationen
Die erste Möglichkeit, Exportladung zu verfolgen, besteht darin, die Buchungsnummer über die API zu teilen. Optional kann die Buchungsnummer um die IMO oder CRN ergänzt werden. Durch das Hinzufügen der IMO oder CRN können die Schiffsinformationen verknüpft werden. Die Erläuterung je Strom lesen Sie unten.
POST
Es ist möglich, eine Buchungnummer über die Buchungsnummer oder die Buchungsnummer mit Schiffsinformationen (IMO oder CRN) zu verfolgen. Durch das Hinzufügen der IMO oder CRN zusätzlich zur Buchungsnummer können ggf. Premium Terminal Data (Add-on für Cargo Controller) geteilt werden.
Response:
Wenn Sie eine Buchung verfolgen, wird eine eindeutige ID registriert und in der Antwort mitgegeben. Hinweis: Die ID in der Response muss in Ihrem eigenen System gespeichert werden, da wir diese ID als Identifikation in allen zukünftigen Updates Ihrer Buchung verwenden.
Webhook event (updates):
Ladung Updates werden geteilt, sobald sie verfügbar sind. In dieser Nachricht wird der zuletzt bekannte Status (state) der Ladung geteilt. Darüber hinaus sendet Portbase auch die event payload mit – mit ausschließlich den Unterschieden gegenüber den letzten Informationen.
In der Abbildung unten sehen Sie eine schematische Darstellung der obigen Erklärung.
Web interface
Im Web interface kann manuell eine Buchungsnummer hinzugefügt werden; optional kann die Buchungsnummer um Schiffsinformationen ergänzt werden, indem das Schiff ausgewählt wird. Ladungsinformationen einer Buchung, die im Web interface verfolgt wird, werden automatisch auch über die API geteilt. Die Erläuterung je Strom lesen Sie unten.
Webhook events (updates):
Das Verfolgen einer Buchung über das Web interface führt bei zukünftigen Events zu Webhook-Updates. Bei diesem zukünftigen Event wird auch zum ersten Mal die eindeutige ID gesendet; diese ID wird von Ihrem System wahrscheinlich nicht erkannt. Sie können selbst entscheiden, ob Sie die Buchungen in Ihrem System speichern. Der aktuelle vollständige Status der Ladung wird geteilt. In dieser Nachricht wird der zuletzt bekannte Status (state) der Ladung geteilt. Darüber hinaus sendet Portbase auch die event payload mit – mit ausschließlich den Unterschieden gegenüber den letzten Informationen.
In der Abbildung unten sehen Sie eine schematische Darstellung der obigen Erklärung.
Über Notification Export Documentation
Im Dienst Notification Export Documentation (NED) wird die Dokumentenvoranmeldung durchgeführt. Buchungen, die von einer Organisation im Dienst NED erstellt werden, werden automatisch an Cargo Controller Export weitergeleitet. Standardmäßig ist die automatische Weiterleitung aktiviert; der Hauptadministrator kann diese deaktivieren. Ladungsinformationen in Cargo Controller Export im Web interface werden automatisch auch über die API geteilt. Optional kann die Buchungsnummer um Schiffsinformationen ergänzt werden, indem das Schiff im Web interface ausgewählt wird. Die Erläuterung je Strom lesen Sie unten.
Booking Number:
Die Buchungsnummer wird aus dem Dienst NED an den Dienst Cargo Controller Export weitergeleitet.
Webhook events (updates):
Das Verfolgen einer Buchung über das Web interface führt bei zukünftigen Events zu Webhook-Updates. Bei diesem zukünftigen Event wird auch zum ersten Mal die eindeutige ID gesendet; diese ID wird von Ihrem System wahrscheinlich nicht erkannt. Sie können selbst entscheiden, ob Sie die Buchungen in Ihrem System speichern. Der aktuelle vollständige Status der Ladung wird geteilt. In dieser Nachricht wird der zuletzt bekannte Status (state) der Ladung geteilt. Darüber hinaus sendet Portbase auch die event payload mit – mit ausschließlich den Unterschieden gegenüber den letzten Informationen.
In der Abbildung unten sehen Sie eine schematische Darstellung der obigen Erklärung.
Kundensystem offline – hinzugefügtes Abonnement
Wenn Ihr System offline geht, gibt es die Möglichkeit, den letzten Status abzufragen. Die Erläuterung je Strom lesen Sie unten.
GET:
Es gibt die Möglichkeit, den Endstatus mittels der SubscriptionID erneut abzufragen.
Response:
Updates werden geteilt, sobald sie verfügbar sind. In dieser Nachricht wird der zuletzt bekannte Status (state) der Ladung geteilt. Darüber hinaus sendet Portbase auch die event payload mit – mit ausschließlich den Unterschieden gegenüber den letzten Informationen.
In der Abbildung unten sehen Sie eine schematische Darstellung der obigen Erklärung.
Implementierungshinweise (Time-outs)
Wenn Sie ein Webhook-Event für eine Buchung erhalten, senden wir diese Updates mit unserer SubscriptionID. Für dieses Update erwarten wir innerhalb von 5 Sekunden eine Antwort. Wenn wir keine Antwort erhalten, wird das Update anschließend noch 3x gesendet.
Wenn der vierte Versuch nicht beantwortet wird, senden wir eine E-Mail mit einer Fehlermeldung und fügen die Payload als Anhang hinzu. Die E-Mail-Adresse wird beim Anfordern der Systemverknüpfung mit Cargo Controller Export angegeben.
Um ggf. fehlende Daten nachzuholen, können Sie die oben beschriebene Implementierung verwenden.
E-Mail-Adresse für API-Fehlermeldungen anpassen?
Das Anfordern der Änderung der Webhook-URL oder der E-Mail-Adresse kann über unsere Abteilung Integration Services erfolgen.
Verknüpfung mit