In diesem Artikel geben wir Hinweise, wie die API von Cargo Controller Import für Ihr eigenes System implementiert werden kann. Dies wird anhand von Use Cases schrittweise erläutert. Jeder Use Case gibt Einblick in die logistische Auswirkung des Datenteilens über Cargo Controller Import. Verpassen Sie keinen Mehrwert, indem Sie alle Datenpunkte in Ihrem eigenen System implementieren.
Dieser Artikel ist relevant für das Projektteam, das die Implementierung realisiert.
Sendungen verfolgen
Cargo Controller Import (CCI) 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 Sendung; die vollständige B/L wird geteilt. Es liegt am Empfänger, die Updates mit unserem vorherigen Update zu vergleichen, um zu sehen, welche Daten geändert wurden.
Um Sendungen erfolgreich zu verfolgen, muss eine Track-Request mindestens 2 Werte enthalten: die Master-B/L-Nummer und mindestens 1 Containernummer.
Die Master-B/L-Nummer muss mit dem SCAC-Code der Reederei versehen sein. Wenn unter der B/L mehrere Container manifestiert sind, teilen wir diese in unseren Updates automatisch für alle bekannten Container.
Szenarien zum Verfolgen von Sendungen
Es gibt 3 Startzeitpunkte für das Verfolgen von Sendungen innerhalb von CC, wodurch Updates an den Webhook gesendet werden. Das Datum, an dem eine Track-Anfrage erstellt wurde, ist der Monat, in dem die bezahlte Transaktion fakturiert wird.
Die Developer-Spezifikationen stehen auf einer separaten Website. In diesen Blöcken verweisen wir auf spezifische Spezifikationen rund um ein Thema.
- Eine Track-Request über ein Softwarepaket. In der Abbildung unten eine Ausarbeitung des Happy Flows
-
Ein Webnutzer trackt manuell Fracht im Webbildschirm von CC. In dieser Situation wird eine eindeutige Track-ID an den Webhook gesendet, für die keine Track-Request gesendet wurde. Dieses Szenario muss nachverfolgt werden:
- Ein Commercial Release wird von Dritten mit Ihrer Organisation verknüpft.
Dies ist nahezu identisch mit Szenario 2. Eine externe Partei verknüpft Ihre Organisation mit der Secure Chain für einen Container, dessen B/L Sie selbst noch nicht tracken. - Fügen Sie die IMO-Nummer oder CRN zu Ihrer Track Request hinzu.
Für Terminals, die Premium Terminal Data bereitstellen, kann es interessant sein, so früh wie möglich Schiffsdaten zu erhalten. Indem Sie diese Daten mitgeben, kann geprüft werden, ob die Schiffsdaten früher verfügbar sind als das Importmanifest.
Warum erhalte ich noch keine Ladungsinformationen?
In den folgenden Szenarien wird von einer Extended-Tracking-Situation ausgegangen. Wenn Sie mehr darüber erfahren möchten, lesen Sie bitte diesen Release Note.
Wenn die Ladung verfolgt wird, kann es sein, dass die Ladungsinformationen in Portbase noch nicht bekannt sind. In diesem Fall registrieren wir Ihre Anfrage und senden automatisch ein Update zurück.
-
Tracked BL: Cargo is tracked and cargo information is available within the PCS. Schematically, it looks like this:
-
Not tracked BL: Cargo is tracked and (as of yet) no cargo information is available within the PCS. Schematically, it looks like this:
-
Deleted BL: The cargo was subsequently removed from the manifest. Schematically, it looks like this:
Warum erhalte ich eine Time-out-E-Mail im Namen der Cargo Controller Import API?
Beim Tracking eines B/L über CC erhalten Sie in der Bestätigung eine eindeutige TrackId, die Ihre Organisation mit diesem spezifischen B/L verknüpft. Auf diese Weise können Sie alle unsere Updates in Ihrem eigenen System einfach miteinander verknüpfen.
Wenn Cargo Controller Import ein Update teilt, wird dieses über die Webhook(s) angeboten, die unter Ihrer Organisation im PCS registriert sind. Wenn Portbase innerhalb von 30 Sekunden keine Response erhält, unternehmen wir einen zweiten Versuch und bei Bedarf einen dritten Versuch.
Wenn nach dem dritten Versuch keine Response auf unser Update erfolgt, senden wir an die E-Mail-Adresse, die beim Webhook registriert ist (eingetragen beim Anfordern der Dienst), eine Time-out-Fehlermeldung: Der Webhook ist nicht verfügbar und Sie verpassen möglicherweise wichtige Updates zu Ihrer Ladung.
Implementierungsempfehlung verhindert Time-out-Fehlermeldungen
Die Erfahrung zeigt, dass viele Organisationen nach dem ersten Update zunächst intern ihren vollständigen Verarbeitungsprozess starten. Erst nachdem dieser Prozess abgeschlossen ist, wird eine Rückmeldung an Portbase zum Erhalt des Webhook-Updates gesendet.
E-Mail-Adresse anpassen für API-Fehlermeldungen?
Die Änderung der E-Mail-Adresse kann über unsere Abteilung Integration Services angefragt werden.
Premium Terminal Data über die API verarbeiten
Für den Erhalt von Premium Terminal Data stellen einige Terminals zusätzliche Anforderungen. Für diese zusätzlichen Daten tracken Sie immer mit einer CRN- oder IMO-Nummer des Schiff.
Wie erhalte ich Premium Terminal Data?
Lesen Sie hier alles darüber, welche Terminals dies anbieten und welche zusätzlichen Bedingungen sie daran knüpfen.
Wenn die Bedingungen erfüllt sind, werden alle neuen B/Ls automatisch mit zusätzlichen Daten versehen. B/Ls aus der Zeit davor werden nicht aktualisiert.
Premium Terminal Data ist Bestandteil unserer Webhook-Updates. Lesen Sie hier mehr über unsere Track Requests.
Schiffsreiseinformationen (Vessel ETA/ETD)
Verfolgen Sie so früh wie möglich die erwartete ETA und ETD von Schiffen, indem Sie Ihre gesamte Ladung mit einer IMO- oder CRN-Nummer tracken.
Die Terminal-ETA und -ETD werden im Objekt geteilt: billOfLading/visitDeclaration/portVisit/berthVisits
Beispiel:
"vesselVisit": {
"crn": "NLRTM21123456",
"portOfCall": {},
"vessel": {},
"visitDeclaration": {
"portVisit": {
"berthVisits": [
{
"berth": {},
"eta": "string",
"ata": "string",
"etd": "string",
"atd": "string",
"etaTerminal": "string",
"etdTerminal": "string"
}
],
"etaPort": "2021-02-28T05:45:00Z",
"etdPort": "2021-02-30T07:30:00Z",
"ataPort": "2021-02-28T05:45:00Z",
"atdPort": "2021-02-30T07:30:00Z"
}
},
"cancelled": false,
"visitStatus": "DEPARTED"
},Erwarteter Entladezeitpunkt (Container EDT)
Für den Erhalt eines erwarteten Entladezeitpunkt ist es erforderlich, dass ein Transportunternehmen nominiert wurde – durch Ihre Organisation oder jemanden in der Secure Chain. Lesen Sie hier mehr über die Nominierung per API.
Die EDT wird pro Container im Objekt geteilt: billOfLading/hinterlandTerminalData/expectedDischargeTime
Beispiel:
"hinterlandTerminalData": [
{
"equipmentNumber": "CONT9434134",
"expectedDischargeTime": "2021-02-28T07:45:00Z",
"gateOut": "2021-02-28T07:45:00Z"
}
],Zollinspektionen mit der Cargo Controller Import API verfolgen
Innerhalb des Dienst Inspection Portal werden Ankündigungen von Inspektionen durch den niederländischen Zoll und Covenant-Parteien (ILT, NVWA usw.) weitergegeben. Die Art der Ankündigung wird in Cargo Controller Import pro Container im Objekt billOfLading/inspectionItems geteilt.
Beispiel:
"inspectionItems": [
{
"equipmentNumber": "CONT9434134",
"inspectionType": "PHYSICAL_OUTLET",
"status": "NOTIFIED",
"dateUpdated": "2021-02-26T07:45:00Z"
}
],Wenn eine Ankündigung erstellt wurde, wird diese durch eine Freigabe (Status released) nachverfolgt.
Wenn keine Ankündigung durch den niederländischen Zoll registriert wurde, erfolgt keinerlei Meldung.
Kommerzielle Freigabe erhalten
Weiter oben im Artikel, im Abschnitt Fracht verfolgen, erläutern wir in Szenario 3 das Verfolgen von Fracht, das durch die Secure Chain gestartet wird.
Möchten Sie mehr über die Secure Chain erfahren? Sehen Sie sich das Einführungsvideo an.
Es gibt 2 Möglichkeiten, mit der Secure Chain verbunden zu werden:
- Die Reederei erteilt Ihrer Organisation eine Freigabe für die Fracht.
- Sie haben nun die Rolle „Release-to Party“. Die Rolle „Release-to Party“ ist einzigartig; alle anderen Rollen in der Secure Chain können mehrfach vorkommen.
- Sie haben nun auch die Rolle Cargo director. Cargo Directors werden pro Container angezeigt; pro Container kann dies eine andere Partei sein.
- Ein Kettenpartner erteilt Ihrer Organisation eine Freigabe für die Fracht.
- Sie haben nun die Rolle Cargo director
Die Secure Chain ist Bestandteil unserer Webhook-Updates. Lesen Sie hier mehr über unsere Track-Requests.
Release-to Party implementieren
Die Rolle „Release-to Party“ folgt pro Container einer kommerziellen Freigabe; diese wird pro Container im Objekt billOfLading/commercialReleases geteilt.
Beispiel:
"commercialReleases": [
{
"equipmentNumber": "CONT9434134",
"releaseToParty": {
"name": "string",
"scacCode": "string"
},
"releaseValidUntilDateTime": "2021-02-28T07:45:00Z"
}
],Cargo director implementieren
Die Rolle Cargo director folgt pro Container einer kommerziellen Freigabe; diese wird pro Container im Objekt billOfLading/cargoDirectors geteilt.
Beispiel:
"cargoDirectors": [
{
"equipmentNumber": "CONT9434134",
"name": "Cargo Director B.V.",
"scacCode": "CD12"
}
],Kommerzielle Freigabe widerrufen
Wenn die kommerzielle Freigabe widerrufen wird, erhalten Sie dazu ein Webhook-Update. Portbase gibt dieses Update weiter, indem die zuvor gesendeten Werte geleert werden (blank value).
Dieser Wert muss pro Container geprüft werden. In diesem Moment muss Kontakt mit der widerrufenden Partei aufgenommen werden: der Reederei oder dem Kettenpartner.
Implementierungsempfehlung: Deadline-Kontrolle der Freigabe
Kommerzielle Freigaben werden häufig mit einer Gültigkeitsfrist geteilt. Führen Sie in Ihrem eigenen System eine Kontrolle durch, ob alle geplanten Aktionen noch innerhalb dieser Frist stattfinden.
- Szenario 1: Die kommerzielle Freigabe ist gültig bis 31-01-2026 23:59. Das Transportunternehmen erhält einen Transportauftrag für 01-02-2026 12:00.
- Szenario 2: Prüfen Sie jeden Tag um 08:00, welche kommerziellen Freigaben abgelaufen sind.
Kommerzielle Freigaben weitergeben
Nach Erhalt der kommerziellen Freigabe gibt es 2 mögliche Optionen:
- Ihre Organisation benennt ein Transportunternehmen (Inland Operator nominieren)
- Ihre Organisation benennt einen (anderen) Spediteur (Cargo director benennen)
Implementierung – Inland Operator nominieren
Ein Inland Operator wird anhand einer eindeutigen EAN-Nummer nominiert. Diese Anmeldung muss Ihre Organisation selbst bei all Ihren Transportunternehmen erfassen und verwalten. Lesen Sie hier unsere CC API-Spezifikationen für die technischen Informationen.
Lesen Sie hier die API-Spezifikationen, um über einen PUT-Request zu nominieren.
Die Rolle des Inland Operator kann pro Container oder für mehrere Container weitergegeben werden. Die Bestätigung erfolgt ausschließlich über die Webhook-Updates; dies wird pro Container im Objekt billOfLading/nominatedInlandOperators geteilt.
Beispiel:
"nominatedInlandOperators": [
{
"equipmentNumber": "CONT9434134",
"inlandOperatorFullName": "Transport B.V."
}
]Das Anpassen der Inland-Operator-Rolle auf ein anderes Transportunternehmen lässt sich einfach realisieren, indem Sie die Aktion erneut mit einer anderen EAN-Nummer ausführen.
Implementierungsempfehlung: Nominieren ohne Importmanifest
Das Nominieren ist ohne Importmanifest möglich; in dieser Situation müssen Sie selbst alle erforderlichen (verpflichtenden) Informationen liefern, um den Nominierungs-Call zu befüllen.
Lesen Sie hier die API-Spezifikationen, um über einen PUT-Request zu nominieren.
Implementierung – Rolle Cargo director weitergeben
Ein Cargo director wird anhand einer eindeutigen iAM Connected ID-Nummer oder einer KvK-Nummer benannt. Diese Anmeldung muss Ihre Organisation selbst bei all Ihren Kettenpartnern erfassen und verwalten.
Die iAM Connected ID-Nummern Ihrer Kettenpartner können über unsere Sales-Abteilung angefragt werden. Nennen Sie dabei auch den Anlass der Anfrage.
Lesen Sie hier die API-Spezifikationen, um einen Cargo director über einen PUT-Request zu benennen.
Die Rolle Cargo director kann pro Container oder für mehrere Container weitergegeben werden. Die Bestätigung erfolgt ausschließlich über die Webhook-Updates; dies wird pro Container im Objekt billOfLading/cargoDirectors geteilt.
Beispiel:
"cargoDirectors": [
{
"equipmentNumber": "CONT9434134",
"name": "Cargo Director B.V.",
"scacCode": "CD12"
}
],Das Anpassen der Cargo-director-Rolle auf einen anderen Kettenpartner lässt sich einfach realisieren, indem Sie die Aktion erneut mit der anderen iAM Connected ID-Nummer oder KvK-Nummer ausführen.
Kommerzielle Freigabe widerrufen
Wenn die kommerzielle Freigabe widerrufen werden muss, können Sie dafür 2 Vorgehensweisen verwenden:
-
Cargo director widerrufen:
- Wiederholen Sie die Aktion, geben Sie jedoch einen leeren Wert für die iAM Connected ID-Nummer oder KvK-Nummer ein.
- Wiederholen Sie die Aktion (benennen oder nominieren), geben Sie jedoch die iAM Connected ID-Nummer oder KvK-Nummer Ihrer eigenen Organisation ein.
-
Inland Operator widerrufen:
- Wiederholen Sie die Aktion, geben Sie jedoch einen leeren Wert für die EAN-Nummer ein.
- Wiederholen Sie die Aktion, geben Sie jedoch direkt einen neuen Wert für die EAN-Nummer eines Transportunternehmens ein.
Das Ergebnis dieser Aktionen wird mittels eines Webhook-Updates bestätigt. Lesen Sie hier mehr über unsere Track-Requests.
Implementierungsempfehlung: Nominieren ohne Importmanifest
Das Nominieren ist ohne Importmanifest möglich; in dieser Situation müssen Sie selbst alle erforderlichen (verpflichtenden) Informationen liefern, um den Nominierungs-Call zu befüllen.
Implementierungsempfehlung: Freigabe nach x Stunden nicht weitergegeben
Kommerzielle Freigaben, die nicht weitergegeben werden, verzögern unnötig den Abholprozess. Führen Sie eine Kontrolle durch, ob die kommerzielle Freigabe innerhalb der Kette bereits nominiert oder autorisiert wurde.
Validieren Sie, ob bereits ein Cargo director oder ein Inland Operator mit Ihrer Fracht verknüpft ist.
Szenario: Ihre Organisation hat die Rolle Cargo director am 31-01-2026 23:59 erhalten. Welche Fracht wurde am 01-02-2026 08.00 noch nicht an einen Inland Operator weitergegeben?
Notification Import Documentation überwachen
Kunden verknüpfen den Dienst Notification Import Documentation (NID) mit den Status, die sie über den Dienst Cargo Controller Import erhalten. Lesen Sie die folgenden Implementierungsempfehlungen, um diese Dienste optimal zu koppeln.
Der Mehrwert der Cargo Controller Import API besteht im vollständigen Auslesen aller verfügbaren Daten. Lesen Sie hier mehr über unsere Track-Requests und die verfügbaren Datenfelder.
Die rechtzeitige Verfügbarkeit eines korrekten Importdokuments für die Fracht ist 1 der 4 Kontrollpunkte eines Terminals. Ohne ein Importdokument wird die Fracht nicht freigegeben. Das Einreichen eines Importdokuments wird als NID-Meldung beschrieben.
Importdokumentations-Status
Die NID-Meldung wird pro Container in Cargo Controller Import zurückgemeldet. Die Bestätigung erfolgt über die Webhook-Updates; dies wird pro Container im Objekt billOfLading/transportEquipmentDeclarations geteilt.
Hinweis! 14 Tage nach Ankunft des Schiffes (ATA Vessel) kann eine NID-Meldung nicht mehr mit CCI verknüpft werden.
Beispiel:
"transportEquipmentDeclarations": [
{
"equipmentNumber": "CONT9434134",
"declarations": [
"DIN"
]
}
],Implementierungsempfehlung: ATA-Container triggert NID-Meldung (EDI)
Innerhalb des Dienstes NID gibt es keine Verknüpfung mit Manifest oder Gate-out. Erstellen Sie in Ihrem eigenen System einen Trigger, der die NID-Meldung in dem Moment sendet, wenn CC die Entladebestätigung für die Fracht erhält.
Die Entladebestätigung wird pro Container im Objekt billOfLading/dischargeReports geteilt.
Beispiel:
"dischargeReports": [
{
"equipmentNumber": "CONT9434134",
"actualDischargeDateTime": "2021-02-28T07:45:00Z",
"dischargeTerminal": {
"code": 4810,
"name": "AMALIAH APMT DSQ",
"ownerFullName": "APM Terminals Maasvlakte II B.V.",
"ownerShortName": "APMII"
}
}
],Implementierungsempfehlung: 6 Stunden nach ATA-Container warnen
Stellen Sie einen Kontrollmechanismus in Ihren eigenen Systemen sicher. Portbase bietet über seine Webbildschirme eine Option zum Versenden eines E-Mail-Alerts. Wenn 6 Stunden nach der Entladebestätigung keine NID-Meldung eingereicht wurde, senden wir eine Warnung per E-Mail.
Diese Meldung können Sie als Benutzer manuell im Webbildschirm von Cargo Controller Import einrichten. Lesen Sie dazu den Artikel E-Mail-Benachrichtigungen in Cargo Controller Import einrichten Sie können diese Warnung auch in Ihre eigenen Systeme integrieren.
Umleitungen von Schiffen abfangen
Bei Umleitungen von Schiffen wird das dischargeTerminal aktualisiert, sobald der Schiffsanlauf (und das Manifest) durch die Schifffahrtsagentur aktualisiert wurde. Wenn sich der POD ändert, weil das Schiff in letzter Minute umgeleitet wird, muss dieses Verhalten sofort abgefangen werden. In Ihren eigenen Systemen könnten bereits Dinge wie die NID-Meldung oder Transportaufträge versendet worden sein.
Erstellen Sie eine Warnung, die prüft, ob sich der POD ändert, nachdem Sie dies getrackt haben.
Der POD wird im Objekt billOfLading/vesselVisit/dischargeTerminal geteilt.
Beispiel:
"dischargeTerminal": {
"code": 4810,
"name": "AMALIAH APMT DSQ",
"ownerFullName": "APM Terminals Maasvlakte II B.V.",
"ownerShortName": "APMII"
},Implementierungsempfehlung: POD ändert sich nach NID-Meldung
Wenn sich der POD ändert, weil das Schiff umgeleitet wird, muss die NID-Meldung beim Terminal des neuen POD eingereicht werden. Die bestehende NID-Meldung beim vorherigen POD muss widerrufen werden. Mehr erfahren? Lesen Sie den Artikel Antrag auf Widerruf eines Importdokuments in Notification Import Documentation.
Erstellen Sie in Ihrem System eine Warnung, die prüft, ob sich der POD ändert, während ein Importdokument bekannt war. Der POD wird im Objekt billOfLading/vesselVisit/dischargeTerminal geteilt.
Beispiel:
"dischargeTerminal": {
"code": 4810,
"name": "AMALIAH APMT DSQ",
"ownerFullName": "APM Terminals Maasvlakte II B.V.",
"ownerShortName": "APMII"
},Terminal Pickup-Daten
Innerhalb der Secure Chain ist der Pickup-Status im Zusammenhang mit der Voranmeldung des Transportunternehmens beim Terminal verfügbar geworden. Ab dem Moment, in dem nominiert wurde, wird beim Terminal ein Status-Request abgefragt. Dieser Status prüft 4 Werte:
- Container vorhanden?
- Zoll-Status?
- Importdokumentations-Status?
- Terminal-Status?
Diese 4 Werte werden regelmäßig aktualisiert, wenn das Transportunternehmen die Planung aktualisiert oder die kommerzielle Freigabe angepasst wird.
Der Mehrwert der Cargo Controller Import API besteht im vollständigen Auslesen aller verfügbaren Daten. Lesen Sie hier mehr über unsere Track-Requests und die verfügbaren Datenfelder.
Der Pickup-Status wird pro Container im Objekt billOfLading/hinterlandPreNotifications geteilt.
Darin wird auch der Zeitpunkt des letzten Updates sowie die Modalität geteilt, mit der die Fracht abgeholt wird.
Beispiel:
"hinterlandPreNotifications": [
{
"equipmentNumber": "string",
"dateUpdated": "string",
"status": "DECLARED",
"modality": "road",
"plannedVisit": {
"eta": "2021-02-28T09:45:00Z",
"ata": "2021-02-28T08:45:00Z"
},
"equipmentStatus": {
"acceptStatuses": [],
"rejectReasons": []
}
}
],Implementierungsempfehlung: Terminal-„reject reasons“ identifizieren
Terminals geben bei jedem Update an, wie der Status der 4 Kontrollpunkte ist. Wenn ein Kontrollpunkt noch nicht den richtigen Status hat, gibt das Terminal dies spezifisch mit einem „reject reason“ zurück. Es kann wertvoll sein, diese Werte zu überwachen und innerhalb Ihrer eigenen Systeme Warnungen auszugeben. Lesen Sie hier , wie dies in den Webbildschirmen angezeigt wird; das liefert Kontext für die Webhook-Updates.
Pro Kontrollpunkt können mehrere „reject reasons“ geteilt werden. Diese werden alle in den Webbildschirmen und in den Webhook-Updates von CCI angezeigt.
Der „reject reason“ wird pro Container im Objekt billOfLading/hinterlandPreNotifications/.../equipmentStatus/rejectReasons geteilt.
Beispiele für „reject reasons“:
- Wenn der Container noch nicht entladen ist, gibt der Container einen „reject reason“ „Container not present“ zurück. Keine Aktion erforderlich.
- Wenn die NID-Meldung nicht eingereicht wurde, lautet der „reject reason“: „Import document missing in Portbase, contact forwarder“. Aktion erforderlich.
Beispiel:
"hinterlandPreNotifications": [
{
"equipmentNumber": "string",
"dateUpdated": "string",
"status": "DECLARED",
"modality": "road",
"plannedVisit": {
"eta": "2021-02-28T09:45:00Z",
"ata": "2021-02-28T08:45:00Z"
},
"equipmentStatus": {
"acceptStatuses": [
{
"type": "AVAILABLE",
"code": "string",
"remark": "string"
}
],
"rejectReasons": [
{
"code": "string",
"terminalDescription": "string",
"parsedReason": "string"
}
]
}
}
],Implementierungsempfehlung: Zeitfenster am Terminal
Nicht alle Terminals verpflichten ein Zeitfenster oder teilen ein Gate-out. Im Containerstatus wird auch der Zeitpunkt geteilt, wenn ein Transportunternehmen ein Zeitfenster am Terminal hat.
Der Pickup-Status wird pro Container im Objekt billOfLading/hinterlandPreNotifications/plannedVisit geteilt.
Beispiel:
"plannedVisit": {
"eta": "2021-02-28T09:45:00Z",
"ata": "2021-02-28T08:45:00Z"
},
Verknüpfung mit