In diesem Artikel geben wir Ihnen Empfehlungen, wie Sie die API von Cargo Controller Export in Ihr eigenes System implementieren können. Stellen Sie sicher, dass Ihnen durch die Implementierung aller Datenpunkte in Ihrem System kein Mehrwert entgeht.
Verfügbare Webhook-Events
Im Artikel Webhook-Events der API für Cargo Controller Export finden Sie eine Übersicht aller verfügbaren Webhook-Events für den Dienst Cargo Controller Export. Die Webhook-Events sind mit den logistischen Auswirkungen verknüpft, damit bestimmt werden kann, welche Datenpunkte für Ihre Organisation wertvoll sind.
Bitte beachten Sie, dass jede Buchung, die von Ihrer Organisation verfolgt wird, zu Transaktionskosten führt – auch dann, wenn sich später herausstellt, dass die Buchung nicht existiert. Beispiel für eine nicht existierende Buchung: Eine Buchung wird im Voraus bei der Schifffahrtsagentur angelegt, wird aber 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, und zwar nur die Unterschiede im Vergleich zu den letzten Informationen. Es liegt an Ihrer Organisation zu entscheiden, nach welcher Logik die Informationen gespeichert werden: Unterschiede innerhalb des 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 sowie 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 andere Weise herstellen. Weiter unten in diesem Artikel finden Sie dazu 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 mit der 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 Prozessfluss lesen Sie unten.
POST
Es ist möglich, eine Buchungsnummer über die Buchungsnummer selbst oder über die Buchungsnummer mit Schiffsinformationen (IMO oder CRN) zu verfolgen. Durch das Hinzufügen von IMO oder CRN neben der 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. Empfehlung: 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):
Ladungs-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, und zwar nur die Unterschiede im Vergleich zu den letzten Informationen.
In der Abbildung unten sehen Sie eine schematische Darstellung der obigen Erläuterung.
Web interface
Im Web interface kann manuell eine Buchungsnummer hinzugefügt werden; optional kann die Buchungsnummer durch Auswahl des Schiffs um Schiffsinformationen ergänzt werden. Ladungsinformationen einer Buchung, die im Web interface verfolgt wird, werden automatisch auch über die API geteilt. Die Erläuterung je Prozessfluss 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, und zwar nur die Unterschiede im Vergleich zu den letzten Informationen.
In der Abbildung unten sehen Sie eine schematische Darstellung der obigen Erläuterung.
Ü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 durch Auswahl des Schiffs im Web interface mit Schiffsinformationen ergänzt werden. Die Erläuterung je Prozessfluss 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, und zwar nur die Unterschiede im Vergleich zu den letzten Informationen.
In der Abbildung unten sehen Sie eine schematische Darstellung der obigen Erläuterung.
Kundensystem offline – hinzugefügtes Abonnement
Wenn Ihr System offline geht, gibt es die Möglichkeit, den letzten Status abzufragen. Die Erläuterung je Prozessfluss lesen Sie unten.
GET:
Es besteht die Möglichkeit, den Endstatus über die 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, und zwar nur die Unterschiede im Vergleich zu den letzten Informationen.
In der Abbildung unten sehen Sie eine schematische Darstellung der obigen Erläuterung.
Implementierungs-Empfehlung (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 3 Mal erneut gesendet.
Wenn der vierte Versuch nicht beantwortet wird, senden wir eine E-Mail mit einer Fehlermeldung und der Payload als Anhang. Die E-Mail-Adresse wird beim Anfordern der Systemverknüpfung mit Cargo Controller Export angegeben.
Um ggf. verpasste Daten nachzuholen, können Sie die oben beschriebene Implementierung verwenden.
Zollinspektionen mit Cargo Controller Export API verfolgen
Innerhalb der Notification Export Documentation (NED) werden Ankündigungen von Inspektionen durch den niederländischen Zoll weitergegeben. Diese Ankündigungen werden in Cargo Controller Export Import in den Objekten InspectionNotified und InspectionReleased geteilt. Unten sehen Sie ein Beispiel für eine vom Zoll angekündigte Inspektion.
eventType": "InspectionNotified",
"payload": {
"bookingNumber": "12345",
"equipmentNumber": " EQTT3000111",
"documentId": "6c0d1b3d-3bdc-40ae-b2c0-85a7ae6082b5",
"documentNumber": "26NL00012345678GF1",
“inspectionType": "PHYSICAL",
“inspectionLocation": "INSPECTION_OUTLET_AREA",
“customsProvidedEquipmentNumber": " EQTT3000111"
}Beispiel für eine vom Zoll freigegebene Inspektion:
eventType": "InspectionReleased",
"payload": {
"bookingNumber": "12345",
"documentId": "6c0d1b3d-3bdc-40ae-b2c0-85a7ae6082b5",
"documentNumber": "26NL00012345678GF1"
}Dokumentenvoranmeldung bei Terminal bekannt
Innerhalb der Notification Export Documentation (NED) gibt das Terminal an, ob es die Buchungsnummer erwartet. Wenn daneben die Dokumentenvoranmeldung erfolgt ist, hat das Terminal die Dokumentenvoranmeldung erhalten. Die Ladung ist bereit, am Terminal angeliefert zu werden.
Wichtig: Für einige Terminals müssen Sie auch über Hinterland Container Notification einen Termin vereinbaren. Dies ist eine separate API, die angefordert werden kann. Mehr dazu steht im Artikel Angeschlossene Terminals und Depots für Hinterland Container Notification.
Dass das Terminal die Buchung erwartet und dass die Dokumentenvoranmeldung erfolgt ist, wird in Cargo Controller Export in den Objekten TerminalSubscribed und DocumentAdded geteilt.
Beispiel: Terminal erwartet Buchung:
eventType": "TerminalSubscribed",
"payload": {
"bookingNumber": "12345",
"orgFullName”: "Rotterdam World Gateway (RWG)"
}Beispiel: Dokumentenvoranmeldung erfolgt:
eventType": "DocumentAdded",
"payload": {
"bookingNumber": "12345",
"equipmentNumber": " EQTT3000111",
"documentId": "6c0d1b3d-3bdc-40ae-b2c0-85a7ae6082b5",
"documentNumber": "26NL00012345678GF1",
“documentType ": "EX",
“createdByOrgFullName ": "Spediteur BV"
}Cargo opening and closing
Wenn das Schiff mit der Dokumentenvoranmeldung verknüpft ist, können cargo opening and closing geteilt werden. Siehe auch Premium Terminal Data (add-on für Cargo Controller). Weitere Informationen dazu, wie die Schiffsinformationen verknüpft werden, finden Sie hier.
cargo opening and closing wird über das Objekt CargoWindowAdded geteilt.
Beispiel: Dokument cargo opening and closing ist bekannt:
eventType": "DocumentAdded",
"payload": {
"callReferenceNumber": "NLRTM26000000",
"cargoOpeningDateTime": "01-04-2026 00:00",
"cargoClosingDateTime": "30-04-2026 23:45",
"terminalFullName": "Rotterdam World Gateway (RWG)",
}E-Mail-Adresse für API-Fehlermeldungen anpassen?
Die Änderung der Webhook-URL oder der E-Mail-Adresse kann über unsere Abteilung Integration Services angefordert werden.
Verknüpfung mit