In dit artikel geven wij advies hoe de API van Cargo Controller Import geïmplementeerd kan worden voor je eigen systeem. Dit wordt stapsgewijs toegelicht aan de hand van use cases. Iedere use case geeft inzicht in de logistieke impact van data delen via Cargo Controller Import. Mis geen enkele toegevoegde waarde door alle datapunten te implementeren in je eigen systeem.
Dit artikel is relevant voor het projectteam dat de implementatie realiseert.
Tracken van lading
Cargo Controller Import (CCI) 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, de volledige B/L wordt gedeeld. Het is aan de ontvanger om de updates te vergelijken met onze vorige update om te zien welke data is gewijzigd.
Om succesvol lading te tracken moet een track request minimaal 2 waardes bevatten: Het master B/L nummer en minimaal 1 containernummer.
Het master B/L nummer moet voorzien zijn van de SCAC code van de rederij. Mocht onder het B/L meerdere containers gemanifesteerd zijn dan delen wij in onze updates deze automatisch voor alle bekende containers.
Lading tracken scenario's
Er zijn 3 start momenten voor het tracken van lading binnen CC waardoor er updates worden gestuurd naar de webhook. De datum waarop een trackverzoek is gemaakt is de maand waarin de betaalde transactie wordt gefactureerd.
De developer specificaties staan op een aparte website. In deze blokjes verwijzen wij naar specificieke specificaties rondom een onderwerp.
- Een track request via een software pakket. In de afbeelding hieronder een uitwerking van de happy flow
-
Een webgebruiker trackt manueel lading in het webscherm van CC. In deze situatie wordt een uniek trackid naar de webhook gestuurd waarvoor geen track request is verstuurd. Dit scenario moet opgevolgd worden:
- Een commercial release wordt gekoppeld door derden aan je organisatie.
Dit is nagenoeg gelijk aan scenario 2. Een externe partij koppelt jouw organisatie aan de Vertrouwensketen voor een container waarvan je de B/L nog niet zelf trackt. - Voeg het IMO nummer of CRN toe aan je track request.
Voor terminals die Premium Terminal data leveren kan het interessant zijn om zo vroeg mogelijk al scheepdata te ontvangen. Door deze data mee te geven kan gekeken worden of de scheepsdata eerder beschikbaar is dan het import manifest.
Waarom ontvang ik nog geen ladinginformatie?
In de onderstaande scenario's wordt uitgegaan van een Extended tracking situatie. Wil je daar meer over weten, lees dan deze release note.
Als lading gevolgd wordt kan het zijn dat de ladinginformatie nog niet bekend is binnen Portbase. Op dat moment registreren we je verzoek en koppelen automatisch een update terug.
-
Tracked BL: Lading is getracked en er is binnen het PCS ladinginformatie is beschikbaar. Schematisch ziet dit er zo uit:
-
Not tracked BL: Lading is getracked en er is binnen het PCS (nog) geen ladinginformatie beschikbaar. Schematisch ziet dit er zo uit:
-
Deleted BL: De lading is naderhand verwijderd van het manifest. Schematisch ziet dit er zo uit:
Waarom krijg ik een time-out e-mail namens Cargo Controller Import API?
Bij het tracken van een B/L via CC ontvang je in de bevestiging een unieke TrackId die je organisatie koppelt aan dit specifieke B/L. Op die manier kan je al onze updates eenvoudig aan elkaar koppelen in je eigen systeem.
Als Cargo Controller Import een update deelt wordt deze aangeboden op de webhook(s) die is geregistreerd onder je organisatie in het PCS. Als Portbase binnen 30 sec geen response ontvangt ondernemen wij een tweede poging en indien nodig een derde poging.
Als na de derde poging geen response volgt op onze update sturen wij naar het e-mailadres dat is geregistreerd bij de webhook (ingevoerd tijdens het aanvragen van de service) een time-out foutmelding: de webhook is niet beschikbaar en je mist mogelijk een belangrijke update(s) over je lading.
Implementatie advies voorkomt time-out foutmeldingen
De ervaring leert dat veel organisaties na de eerste update eerst intern hun volledige verwerkingsproces activeren. Pas nadat dit proces is afgehandeld wordt daarmee pas een reactie gestuurd richting Portbase op de ontvangst van de webhook update.
E-mailadres aanpassen voor API foutmeldingen?
Het wijzigingen van het e-mailadres kan worden aangevraagd via onze afdeling Integration Services.
Premium Terminal Data verwerken de API
Voor het ontvangen van Premium Terminal Data stellen sommige terminals aanvullende eisen. Track voor deze aanvullende data altijd met een CRN of IMO nummer van het schip.
Hoe ontvang ik Premium Terminal Data?
Lees hier alles over welke terminals dit aanbieden en de aanvullende voorwaarden die zij hieraan verbinden.
Als aan de voorwaarden is voldaan worden alle nieuwe B/L's automatisch voorzien van aanvullende data. B/L's van voor die tijd worden niet bijgewerkt.
Premium Terminal Data is onderdeel van onze webhook updates. Lees hier meer over onze track requests.
Scheepsreis informatie (Vessel ETA/ETD)
Volg zo vroeg mogelijk de verwachte ETA en ETD van schepen door al je lading te tracken met een IMO of CRN nummer.
De termina ETA en ETD worden gedeeld in het object: billOfLading/visitDeclaration/portVisit/berthVisits
Voorbeeld:
"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"
},Verwacht losmoment (Container EDT)
Voor het ontvangen van een verwacht losmoment is het noodzakelijk dat er een vervoerder is genomineerd. Door jouw organisatie of iemand in de Vertrouwensketen. Lees hier meer over het nomineren via API.
De EDT wordt gedeeld per container in het object: billOfLading/hinterlandTerminalData/expectedDischargeTime
Voorbeeld:
"hinterlandTerminalData": [
{
"equipmentNumber": "CONT9434134",
"expectedDischargeTime": "2021-02-28T07:45:00Z",
"gateOut": "2021-02-28T07:45:00Z"
}
],Douane inspecties volgen met Cargo Controller Import API
Binnen de service Inspectieportaal worden aanzeggingen van inspecties door de Nederlandse Douane en covenant partijen (ILT, NVWA, etc.) doorgegeven. De soort aanzegging worden in Cargo Controller Import gedeeld per container in het object: billOfLading/inspectionItems
Voorbeeld:
"inspectionItems": [
{
"equipmentNumber": "CONT9434134",
"inspectionType": "PHYSICAL_OUTLET",
"status": "NOTIFIED",
"dateUpdated": "2021-02-26T07:45:00Z"
}
],Als een aanzegging is gemaakt wordt deze opgevolgd met een vrijstelling (status released).
Wanneer er geen aanzegging is geregistreerd door de Nederlandse Douane volgt er geen enkele melding.
Commerciële vrijstelling ontvangen
Hierboven in het artikel, in de kop Lading tracken, vertellen we in scenario 3 over het tracken van lading dat gestart wordt door de Vertrouwensketen.
Wil je meer weten over de Vertrouwensketen? Bekijk de introductie video.
Er zijn 2 manieren om verbonden te worden aan de Vertrouwensketen:
- De rederij stelt de lading aan jouw organisatie vrij.
- Je hebt nu de rol van Release-to Party. De rol van Release-to Party is uniek, alle overige rollen in de Vertrouwensketen kunnen meerdere keren voorkomen.
- Je hebt nu ook de rol van Cargo Director. Cargo Directors worden per container getoond, per container kan dit een ander partij zijn.
- Een ketenpartner stelt de lading aan jouw organisatie vrij.
- Je hebt nu de rol van Cargo Director
De Vertrouwensketen is onderdeel van onze webhook updates. Lees hier meer over onze track requests.
Release-to Party implementeren
De rol van Release-to Party volgt per container een commerciële vrijstelling, dit wordt gedeeld per container in het object: billOfLading/commercialReleases.
Voorbeeld:
"commercialReleases": [
{
"equipmentNumber": "CONT9434134",
"releaseToParty": {
"name": "string",
"scacCode": "string"
},
"releaseValidUntilDateTime": "2021-02-28T07:45:00Z"
}
],Cargo Director implementeren
De rol van Cargo Director volgt per container een commerciële vrijstelling, dit wordt gedeeld per container in het object: billOfLading/cargoDirectors.
Voorbeeld:
"cargoDirectors": [
{
"equipmentNumber": "CONT9434134",
"name": "Cargo Director B.V.",
"scacCode": "CD12"
}
],Intrekken commerciële vrijstelling
Als de commerciële vrijstelling ingetrokken wordt ontvang je daar een webhook update over. Portbase deelt deze update door de eerder gestuurde waardes leeg te maken (blank value).
Die waarde zal per container gecontroleerd moeten worden. Op dat moment moet er contact opgenomen worden met de intrekkende partij; De rederij of de ketenpartner.
Implementatie advies: deadline vrijstelling controle
Commerciële vrijstellingen worden vaak gedeeld met een geldigheidstermijn. Voer een controle uit in je eigen systeem of alle acties die gepland staan nog wel binnen dit termijn plaatsvinden.
- Scenario 1: De commerciële vrijstelling is geldig tot 31-01-2026 23:59. De vervoerder ontvangt een transportopdracht voor 01-02-2026 12:00.
- Scenario 2: Controleer iedere dag om 08:00 welke commerciële vrijstellingen zijn verlopen.
Commerciële vrijstellingen doorgeven
Na ontvangst van de commerciële vrijstelling zijn er 2 mogelijke keuzes:
- Jouw organisatie wijst een vervoerder aan (Inland Operator nomineren)
- Jouw organisatie wijst een (andere) expediteur aan (Cargo Director aanwijzen)
Implementatie - Inland Operator nomineren
Een inland operator wordt genomineerd op basis een uniek EAN-nummer. Die registratie moet je organisatie zelf verzamelen en beheren van al je vervoerders. Lees hier onze CC API specificaties voor de technische informatie.
Lees hier de API specificaties om te nomineren via een PUT request.
De rol van Inland Operator kan per container, of voor meerdere containers worden doorgezet. Alleen via de webhook updates volgt de bevestiging, dit wordt gedeeld per container in het object: billOfLading/nominatedInlandOperators.
Voorbeeld:
"nominatedInlandOperators": [
{
"equipmentNumber": "CONT9434134",
"inlandOperatorFullName": "Transport B.V."
}
]Het aanpassen van de Inland Operator rol naar een andere vervoerder is eenvoudig te realiseren door de actie opnieuw uit te voeren met een ander EAN-nummer.
Implementatie advies: Nomineren zonder import manifest
Het nomineren kan zonder import manifest, in die situatie zal je zelf alle benodigde (verplichte) informatie moeten aanleveren om de nominatie-call te vullen.
Lees hier de API specificaties om te nomineren via een PUT request.
Implementatie - rol Cargo Director doorgeven
Een Cargo Director wordt aangewezen op basis een uniek iAM Connected ID-nummer of een KvK-nummer. Die registratie moet je organisatie zelf verzamelen en beheren van al je ketenpartners.
De iAM Connected ID-nummer van je ketenpartners zijn opvraagbaar via onze Sales afdeling. Benoem hierbij ook de aanleiding van het verzoek.
Lees hier de API specificaties om een Cargo Director aan te wijzen via een PUT request.
De rol van Cargo Director kan per container, of voor meerdere containers worden doorgezet. Alleen via de webhook updates volgt de bevestiging, dit wordt gedeeld per container in het object: billOfLading/cargoDirectors.
Voorbeeld:
"cargoDirectors": [
{
"equipmentNumber": "CONT9434134",
"name": "Cargo Director B.V.",
"scacCode": "CD12"
}
],Het aanpassen van de Cargo Director rol naar een andere ketenpartner is eenvoudig te realiseren door de actie opnieuw uit te voeren met het andere iAM Connected ID-nummer of KvK-nummer.
Intrekken commerciële vrijstelling
Als de commerciële vrijstelling ingetrokken moet worden kan je hiervoor 2 werkwijzes hanteren:
-
Intrekken Cargo Director:
- Herhaal de actie maar voer een blanco waarde in voor het iAM Connected ID-nummer of KvK-nummer.
- Herhaal de actie (aanwijzen of nomineren) maar voer het iAM Connected ID-nummer of KvK-nummer van je eigen organisatie in.
-
Intrekken Inland Operator:
- Herhaal de actie maar voer een blanco waarde in voor het EAN-nummer.
- Herhaal de actie maar voer direct een nieuwe waarde in voor het EAN-nummer van een vervoerder.
De uitkomst van deze acties worden bevestigd d.m.v. een webhook update. Lees hier meer over onze track requests.
Implementatie advies: Nomineren zonder import manifest
Het nomineren kan zonder import manifest, in die situatie zal je zelf alle benodigde (verplichte) informatie moeten aanleveren om de nominatie-call te vullen.
Implementatie advies: Vrijstelling na x-uur niet doorgegeven
Commerciële vrijstellingen die niet doorgezet worden vertragen onnodig het ophaalproces. Voer een controle uit of de commerciële vrijstelling al genomineerd of gemachtigd is binnen de keten.
Valideer of er al een Cargo Director of een Inland Operator is gekoppeld aan je lading.
Scenario: Je organisatie heeft de rol Cargo Director ontvangen op 31-01-2026 23:59. Welke lading is op 01-02-2026 08.00 nog niet doorgezet naar een Inland Operator?
Melding Import Documentatie monitoren
Klanten koppelen de service Melding Import Documentatie (MID) aan de statussen die zij verkrijgen via de service Cargo Controller Import. Lees de onderstaande implementatie adviezen om deze services optimaal te koppelen.
De toegevoegde waarde van Cargo Controller Import API is het volledig uitlezen van alle beschikbare data. Lees hier meer over onze track requests en de beschikbare data velden.
De tijdige aanwezigheid van een correct import document van de lading is 1 van de 4 controle punten van een terminal. Zonder een import document wordt de lading niet vrijgegeven. Het insturen van een Import document wordt omschreven als een MID-melding.
Import Documentatie status
De MID-melding wordt per container teruggekoppeld in Cargo Controller Import. Via de webhook updates volgt de bevestiging, dit wordt gedeeld per container in het object: billOfLading/transportEquipmentDeclarations.
Let op! 14 dagen na aankomst schip (ATA Vessel) kan een MID-melding niet meer worden gekoppeld met CCI.
Voorbeeld:
"transportEquipmentDeclarations": [
{
"equipmentNumber": "CONT9434134",
"declarations": [
"DIN"
]
}
],Implementatie advies: ATA Container trigger MID-melding (EDI)
Binnen de service MID is er geen koppeling met manifest of gate out. Creëer een trigger in je eigen systeem die de MID-melding instuurt op het moment dat CC de losbevestiging ontvangt van de lading.
De losbevestiging wordt per container gedeeld in het object: billOfLading/dischargeReports.
Voorbeeld:
"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"
}
}
],Implementatie advies: 6 uur na ATA Container waarschuwen
Zorg voor een controle mechanisme binnen je eigen systemen. Portbase hanteert via haar webschermen een optie om een e-mailalert te versturen. Als er geen MID-melding is ingestuurd 6 uur na de losbevestiging, dan versturen wij een waarschuwing per e-mail.
Deze melding kan je handmatig instellen als gebruiker in het webscherm van Cargo Controller Import . Lees hiervoor het artikel E-mailnotificaties instellen in Cargo Controller Import Je kan deze waarschuwing ook in je eigen systemen integreren.
Uitwijken van schepen opvangen
Bij het uitwijken van schepen wordt de discharge terminal bijgewerkt zodat het scheepsbezoek (en manifest) zijn bijgewerkt door de cargadoor. Als de POD wijzigt omdat het schip last-minute uitwijkt, is het noodzakelijk dat dit gedrag direct wordt afgevangen. In je eigen systemen zijn er mogelijk al zaken zoals de MID-melding of transportopdrachten verstuurd.
Creeër een waarschuwing die controleert of de POD wijzigt nadat je dit hebt getracked.
De POD wordt gedeeld in het object: billOfLading/vesselVisit/dischargeTerminal.
Voorbeeld:
"dischargeTerminal": {
"code": 4810,
"name": "AMALIAH APMT DSQ",
"ownerFullName": "APM Terminals Maasvlakte II B.V.",
"ownerShortName": "APMII"
},Implementatie advies: POD wijzigt na MID-melding
Als de POD wijzigt omdat het schip uitwijkt, is het noodzakelijk dat de MID-melding bij de nieuwe POD terminal wordt ingediend. De bestaande MID-melding bij de vorige POD moet worden ingetrokken. Meer weten? Lees het artikel Verzoek tot intrekken importdocument in Melding Import Documentatie.
Creeër in jouw systeem een waarschuwing die controleert of de POD wijzigt terwijl een import document bekend was. De POD wordt gedeeld in het object: billOfLading/vesselVisit/dischargeTerminal.
Voorbeeld:
"dischargeTerminal": {
"code": 4810,
"name": "AMALIAH APMT DSQ",
"ownerFullName": "APM Terminals Maasvlakte II B.V.",
"ownerShortName": "APMII"
},Terminal pickup data
Binnen de Vertrouwensketen is de pickup status beschikbaar gekomen rondom de voormelding van vervoerder bij de terminal. Vanaf het moment dat er is genomineerd wordt er een status request uitgevraagd bij de terminal. Deze status controleert 4 waardes:
- Container aanwezig?
- Douane status?
- Import documentatie status?
- Terminal status?
Deze 4 waardes worden geregeld bijgewerkt als de vervoerder de planning bijwerkt of de commerciële vrijstelling wordt aangepast.
De toegevoegde waarde van Cargo Controller Import API is het volledig uitlezen van alle beschikbare data. Lees hier meer over onze track requests en de beschikbare data velden.
De pickup status wordt per container gedeeld in het object: billOfLading/hinterlandPreNotifications.
Hierin wordt ook gedeeld wat het laatste update moment was en de modaliteit waarmee de lading opgehaald gaat worden.
Voorbeeld:
"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": []
}
}
],Implementatie advies: Terminal reject reasons identificeren
Terminals geven bij iedere update aan wat de status is van de 4 controle punten. Als een controle punt nog niet de juiste status heeft geeft de terminal dit specifiek terug met een 'reject reason'. Het kan waardevol zijn om deze waardes te monitoren en te waarschuwen binnen je eigen systemen.
Per controlepunt kunnen er meerdere reject reasons worden gedeeld. Deze worden allemaal getoond in de webschermen en in de webhook updates van CCI.
De reject reason wordt per container gedeeld in het object: billOfLading/hinterlandPreNotifications/.../equipmentStatus/rejectReasons.
Voorbeelden van reject reasons:
- Als de container nog niet gelost is, zal de container een reject reason geven 'Container not present'. Geen actie noodzakelijk.
- Als de MID-melding niet ingediend is, dan zal de reject reason zijn: 'Import document missing in Portbase, contact forwarder'. Actie noodzakelijk.
Voorbeeld:
"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"
}
]
}
}
],Implementatie advies: Tijdslot terminal
Niet alle terminals verplichten een tijdslot of delen een gate out. Binnen de container status wordt ook het tijdstip gedeeld als een vervoerder een tijdslot heeft op de terminal.
De pickup status wordt per container gedeeld in het object: billOfLading/hinterlandPreNotifications/plannedVisit.
Voorbeeld:
"plannedVisit": {
"eta": "2021-02-28T09:45:00Z",
"ata": "2021-02-28T08:45:00Z"
},
Gerelateerd aan