In dit artikel geven we advies over hoe je de API van Cargo Controller Export kan implementeren in je eigen systeem. Zorg ervoor dat je geen toegevoegde waarde mist door alle datapunten in je systeem te implementeren.
Beschikbare webhook events
In het artikel Webhook events van de API voor Cargo Controller Export zie je een overzicht van alle beschikbare webhook events voor de service Cargo Controller Export. De webhook events zijn gekoppeld aan de logistiek impact zodat bepaald kan worden welke datapunten waardevol zijn voor jouw organisatie.
Hou er rekening mee dat elke boeking die door jouw organisatie wordt gevolgd resulteert in transactiekosten, ook wanneer de boeking uiteindelijk niet blijkt te bestaan. Voorbeeld van een niet-bestaande boeking: een boeking wordt vooraf aangemaakt bij de cargadoor, maar wordt uiteindelijk niet uitgevoerd.
Tracken van export lading
Cargo Controller Export werkt met een RESTful API en Webhook (HTTPS calls). De specificaties vind je hier.
In de webhook updates versturen wij de laatste bekende status (state) van je lading. Hiernaast stuurt Portbase ook de event payload mee met alleen de verschillen ten opzichte van de laatste informatie. Het is aan jouw organisatie om te bepalen op basis van welke logica de informatie wordt opgeslagen: verschillen tussen de state of het verwerken van de event payload.
In Cargo Controller Import wordt alleen state verstuurd niet de event payload.
Scheepsinformatie zoals ETA-, ETD-, ATA- en ATD- schip en cargo window (cargo opening and closing) wordt Premium Terminal Data genoemd. Meer informatie over deze datapunten is hier te vinden.
Als je toegang hebt tot deze datapunten, dan kan je ook de boeking aan de scheepsinformatie koppelen. Wanneer de cargadoor de laadlijst aan Portbase stuurt kunnen wij de koppeling maken tussen boekingsnummer en scheepsinformatie. Deze koppeling kan je ook via andere wegen maken. Verderop in dit artikel vind je hier meer over.
Track jouw export lading
Er zijn 3 manieren om een boekingsnummer te volgen:
- API – met of zonder scheepsinformatie
- Web interface
- Via Melding Export Documentatie
API – met of zonder scheepsinformatie
De eerste mogelijkheid om export lading te volgen is door het boekingsnummer te delen via de API. Eventueel kan het boekingsnummer aangevuld worden met het IMO of CRN. Door het IMO of CRN toe te voegen kan de scheepsinformatie gekoppeld worden. De toelichting per stroom lees je hieronder.
POST
Het is mogelijk om een boekingnummer te volgen via het boekingsnummer of het boekingsnummer met scheepsinformatie (IMO of CRN). Door naast het boekingsnummer ook het IMO of CRN toe te voegen kan eventueel Premium Terminal Data (add-on voor Cargo Controller) gedeeld worden.
Response:
Wanneer je een boeking volgt, wordt een uniek ID geregistreerd en meegegeven in het antwoord. Advies: het ID in de response moet in je eigen systeem worden opgeslagen, omdat wij dit ID gebruiken als identificatie in alle toekomstige updates van je boeking.
Webhook event (updates):
Lading updates worden gedeeld zodra beschikbaar. In dit bericht wordt de laatste bekende status (state) van de lading gedeeld. Hiernaast stuurt Portbase ook de event payload mee met alleen de verschillen ten opzichte van de laatste informatie.
In de afbeelding hieronder zie je een schematische weergaven van de uitleg hierboven.
Web interface
In de web interface kan manueel een boekingsnummer worden toegevoegd, eventueel kan het boekingsnummer aangevuld worden met scheepsinformatie door het schip te selecteren. Lading informatie van een boeking die gevolgd wordt in de web interface wordt automatisch ook gedeeld via de API. De toelichting per stroom lees je hieronder.
Webhook events (updates):
Het volgen van een boeking via de web interface resulteert in webhook-updates bij toekomstige events. Bij dit toekomstige event wordt ook voor het eerst het unieke ID gestuurd, dit ID wordt waarschijnlijk niet herkend door je systeem. Je kunt zelf beslissen of je de boekingen in je systeem opslaat. De huidige volledige status van de lading wordt gedeeld. In dit bericht wordt de laatste bekende status (state) van de lading gedeeld. Hiernaast stuurt Portbase ook de event payload mee met alleen de verschillen ten opzichte van de laatste informatie.
In de afbeelding hieronder zie je een schematische weergaven van de uitleg hierboven.
Via Melding Export Documentatie
In de service Melding Export Documentatie (MED) wordt de documentvoormelding gedaan. Boekingen gemaakt door een organisatie in de service MED worden automatisch doorgezet aan Cargo Controller Export. Standaard staat het automatisch doorzetten aan, de hoofdbeheerder kan dit uitzetten. Lading informatie in Cargo Controller Export in de web interface wordt automatisch ook gedeeld via de API. Eventueel kan het boekingsnummer aangevuld worden met scheepsinformatie door het schip te selecteren in de web interface. De toelichting per stroom lees je hieronder.
Booking Number:
Het boekibgsnummer wordt vanuit de service MED doogezet aan de servic Cargo Controller Export.
Webhook events (updates):
Het volgen van een boeking via de web interface resulteert in webhook-updates bij toekomstige events. Bij dit toekomstige event wordt ook voor het eerst het unieke ID gestuurd, dit ID wordt waarschijnlijk niet herkend door je systeem. Je kunt zelf beslissen of je de boekingen in je systeem opslaat. De huidige volledige status van de lading wordt gedeeld. In dit bericht wordt de laatste bekende status (state) van de lading gedeeld. Hiernaast stuurt Portbase ook de event payload mee met alleen de verschillen ten opzichte van de laatste informatie.
In de afbeelding hieronder zie je een schematische weergaven van de uitleg hierboven.
Klantsysteem offline - toegevoegd abonnement
Als je systeem offline gaat, is er de mogelijkheid om de laatste status op te vragen. De toelichting per stroom lees je hieronder.
GET:
Er is de mogelijkheid om de eindstatus opnieuw op te vragen middels het SubscriptionID.
Response:
Updates worden gedeeld wanneer beschikbaar. In dit bericht wordt de laatste bekende status (state) van de lading gedeeld. Hiernaast stuurt Portbase ook de event payload mee met alleen de verschillen ten opzichte van de laatste informatie.
In de afbeelding hieronder zie je een schematische weergaven van de uitleg hierboven.
Implementatie advies (time-outs)
Wanneer je een webhook-event ontvangt voor een boeking, versturen wij deze updates met onze SubscriptionID. Op deze update verwachten wij een antwoord binnen 5 seconden. Als we geen antwoord krijgen zal hierna de update nogmaals 3x verstuurd worden.
Wanneer de vierde poging niet wordt beantwoord, sturen wij een e‑mail met een foutmelding en de payload toegevoegd als bijlage. Het e-mail adres wordt opgegeven tijdens het aanvragen van de systeemkoppeling met Cargo Controller Export.
Om eventueel gemiste data op te halen kan je de implementatie hierboven gebruiken.
Douane inspecties volgen met Cargo Controller Export API
Binnen de Melding Export Documentatie (MED) aanzeggingen van inspecties door de Nederlandse Douane doorgegeven. Deze aanzegging worden in Cargo Controller Export Import gedeeld in het object: InspectionNotified en InspectionReleased. Hieronder zie je een voorbeeld inspectie aangezegd door Douane
eventType": "InspectionNotified",
"payload": {
"bookingNumber": "12345",
"equipmentNumber": " EQTT3000111",
"documentId": "6c0d1b3d-3bdc-40ae-b2c0-85a7ae6082b5",
"documentNumber": "26NL00012345678GF1",
“inspectionType": "PHYSICAL",
“inspectionLocation": "INSPECTION_OUTLET_AREA",
“customsProvidedEquipmentNumber": " EQTT3000111"
}Voorbeeld inspectie vrijgegeven door Douane:
eventType": "InspectionReleased",
"payload": {
"bookingNumber": "12345",
"documentId": "6c0d1b3d-3bdc-40ae-b2c0-85a7ae6082b5",
"documentNumber": "26NL00012345678GF1"
}Document voormelding bekend bij terminal
Binnen de Melding Export Documentatie (MED) geeft de terminal aan of deze het boekingsnummer verwacht. Als de hiernaast de document voormelding gedaan is, heeft de terminal de document voormelding ontvangen. De lading is gereed om afgeleverd te worden bij de terminal.
Belangrijk: voor sommige terminals moet je ook een afspraak maken via Melding Container Achterland. Dit is een aparte API die aangevraagd kan worden. Meer hierover staat in het artikel Aangesloten terminals en depots voor Melding Container Achterland.
Dat de terminal de boeking verwacht en dat de document voormelding gedaan is wordt in Cargo Controller Export gedeeld in het object: TerminalSubscribed en DocumentAdded.
Voorbeeld Terminal verwacht boeking:
eventType": "TerminalSubscribed",
"payload": {
"bookingNumber": "12345",
"orgFullName”: "Rotterdam World Gateway (RWG)"
}Voorbeeld document voormelding gedaan:
eventType": "DocumentAdded",
"payload": {
"bookingNumber": "12345",
"equipmentNumber": " EQTT3000111",
"documentId": "6c0d1b3d-3bdc-40ae-b2c0-85a7ae6082b5",
"documentNumber": "26NL00012345678GF1",
“documentType ": "EX",
“createdByOrgFullName ": "Expediteur BV"
}Cargo opening and closing
Als het schip gekoppeld is aan de document voormelding kan de cargo opening en closing gedeeld worden. Zie ook Premium Terminal Data (add-on voor Cargo Controller). Meer informatie over hoe de scheepsinformatie gekoppeld wordt vind je hier.
De cargo opening en closing wordt gedeeld via het object: CargoWindowAdded.
Voorbeeld document cargo opening en closing is bekend:
eventType": "DocumentAdded",
"payload": {
"callReferenceNumber": "NLRTM26000000",
"cargoOpeningDateTime": "01-04-2026 00:00",
"cargoClosingDateTime": "30-04-2026 23:45",
"terminalFullName": "Rotterdam World Gateway (RWG)",
}E-mailadres aanpassen voor API foutmeldingen?
Het wijzigingen van de webhook URL of e-mailadres kan worden aangevraagd via onze afdeling Integration Services.
Gerelateerd aan