In this article we provide advice on how you can implement the API of Cargo Controller Export in your own system. Make sure you don’t miss any added value by implementing all data points in your system.
Available webhook events
In the article Webhook events of the API for Cargo Controller Export you will find an overview of all available webhook events for the service Cargo Controller Export. The webhook events are linked to the logistics impact so it can be determined which data points are valuable for your organisation.
Please note that every booking tracked by your organisation results in transaction costs, even if the booking ultimately turns out not to exist. Example of a non-existent booking: a booking is created in advance with the agent, but is ultimately not executed.
Tracking export cargo
Cargo Controller Export works with a RESTful API and Webhook (HTTPS calls). You can find the specifications here.
In the webhook updates, we send the most recently known status (state) of your cargo. In addition, Portbase also sends the event payload containing only the differences compared to the most recent information. It is up to your organisation to decide, based on which logic, the information is stored: differences between the state or processing the event payload.
In Cargo Controller Import, only state is sent, not the event payload.
Vessel information such as ETA, ETD, ATA and ATD of the vessel and the cargo window (cargo opening and closing) is called Premium Terminal Data. More information about these data points can be found here.
If you have access to these data points, you can also link the booking to the vessel information. When the agent sends the loading list to Portbase, we can create the link between booking number and vessel information. You can also create this link in other ways. Further on in this article you will find more about this.
Track your export cargo
There are 3 ways to track a booking number:
- API – with or without vessel information
- Web interface
- Via Notification Export Documentation
API – with or without vessel information
The first way to track export cargo is by sharing the booking number via the API. Optionally, the booking number can be supplemented with the IMO or CRN. By adding the IMO or CRN, the vessel information can be linked. You can read the explanation per flow below.
POST
It is possible to track a booking number via the booking number itself, or the booking number with vessel information (IMO or CRN). By adding the IMO or CRN alongside the booking number, Premium Terminal Data (add-on for Cargo Controller) can potentially be shared.
Response:
When you track a booking, a unique ID is registered and returned in the response. Recommendation: the ID in the response must be stored in your own system, because we use this ID as identification in all future updates of your booking.
Webhook event (updates):
Cargo updates are shared as soon as they are available. In this message the most recently known status (state) of the cargo is shared. In addition, Portbase also sends the event payload containing only the differences compared to the most recent information.
In the image below you will see a schematic representation of the explanation above.
Web interface
In the web interface, a booking number can be added manually. Optionally, the booking number can be supplemented with vessel information by selecting the vessel. Cargo information for a booking that is tracked in the web interface is automatically also shared via the API. You can read the explanation per flow below.
Webhook events (updates):
Tracking a booking via the web interface results in webhook updates for future events. With this future event, the unique ID is also sent for the first time; this ID will probably not be recognised by your system. You can decide yourself whether you store the bookings in your system. The current full status of the cargo is shared. In this message the most recently known status (state) of the cargo is shared. In addition, Portbase also sends the event payload containing only the differences compared to the most recent information.
In the image below you will see a schematic representation of the explanation above.
Via Notification Export Documentation
In the service Notification Export Documentation (NED), the document pre-notification is made. Bookings created by an organisation in the service NED are automatically passed through to Cargo Controller Export. By default, automatic passing through is enabled; the main administrator can disable this. Cargo information in Cargo Controller Export in the web interface is automatically also shared via the API. Optionally, the booking number can be supplemented with vessel information by selecting the vessel in the web interface. You can read the explanation per flow below.
Booking Number:
The booking number is passed from the service NED to the service Cargo Controller Export.
Webhook events (updates):
Tracking a booking via the web interface results in webhook updates for future events. With this future event, the unique ID is also sent for the first time; this ID will probably not be recognised by your system. You can decide yourself whether you store the bookings in your system. The current full status of the cargo is shared. In this message the most recently known status (state) of the cargo is shared. In addition, Portbase also sends the event payload containing only the differences compared to the most recent information.
In the image below you will see a schematic representation of the explanation above.
Customer system offline - subscription added
If your system goes offline, there is an option to retrieve the latest status. You can read the explanation per flow below.
GET:
There is an option to retrieve the final status again using the SubscriptionID.
Response:
Updates are shared when available. In this message the most recently known status (state) of the cargo is shared. In addition, Portbase also sends the event payload containing only the differences compared to the most recent information.
In the image below you will see a schematic representation of the explanation above.
Implementation advice (time-outs)
When you receive a webhook event for a booking, we send these updates with our SubscriptionID. For this update we expect a response within 5 seconds. If we do not receive a response, the update will be resent 3 more times.
If the fourth attempt is not answered, we send an email with an error message and the payload added as an attachment. The email address is provided when you request the system interface with Cargo Controller Export.
To retrieve any missed data, you can use the implementation above.
Tracking customs inspections with Cargo Controller Export API
Within Notification Export Documentation (NED), notifications of inspections by Dutch Customs are communicated. These notifications are shared in Cargo Controller Export Import in the object: InspectionNotified and InspectionReleased. Below you will see an example of an inspection notified by Customs.
eventType": "InspectionNotified",
"payload": {
"bookingNumber": "12345",
"equipmentNumber": " EQTT3000111",
"documentId": "6c0d1b3d-3bdc-40ae-b2c0-85a7ae6082b5",
"documentNumber": "26NL00012345678GF1",
“inspectionType": "PHYSICAL",
“inspectionLocation": "INSPECTION_OUTLET_AREA",
“customsProvidedEquipmentNumber": " EQTT3000111"
}Example inspection released by Customs:
eventType": "InspectionReleased",
"payload": {
"bookingNumber": "12345",
"documentId": "6c0d1b3d-3bdc-40ae-b2c0-85a7ae6082b5",
"documentNumber": "26NL00012345678GF1"
}Document pre-notification known at terminal
Within Notification Export Documentation (NED), the terminal indicates whether it expects the booking number. If, in addition, the document pre-notification has been made, the terminal has received the document pre-notification. The cargo is ready to be delivered to the terminal.
Important: for some terminals you also need to make an appointment via Hinterland Container Notification. This is a separate API that can be requested. More about this can be found in the article Connected terminals and depots for Hinterland Container Notification.
That the terminal expects the booking and that the document pre-notification has been made is shared in Cargo Controller Export in the object: TerminalSubscribed and DocumentAdded.
Example terminal expects booking:
eventType": "TerminalSubscribed",
"payload": {
"bookingNumber": "12345",
"orgFullName”: "Rotterdam World Gateway (RWG)"
}Example document pre-notification done:
eventType": "DocumentAdded",
"payload": {
"bookingNumber": "12345",
"equipmentNumber": " EQTT3000111",
"documentId": "6c0d1b3d-3bdc-40ae-b2c0-85a7ae6082b5",
"documentNumber": "26NL00012345678GF1",
“documentType ": "EX",
“createdByOrgFullName ": "Forwarder BV"
}Cargo opening and closing
If the vessel is linked to the document pre-notification, the cargo opening and closing can be shared. See also Premium Terminal Data (add-on for Cargo Controller). More information about how the vessel information is linked can be found here.
The cargo opening and closing is shared via the object: CargoWindowAdded.
Example: document cargo opening and closing is known:
eventType": "DocumentAdded",
"payload": {
"callReferenceNumber": "NLRTM26000000",
"cargoOpeningDateTime": "01-04-2026 00:00",
"cargoClosingDateTime": "30-04-2026 23:45",
"terminalFullName": "Rotterdam World Gateway (RWG)",
}Adjust email address for API error messages?
Requesting changes to the webhook URL or email address can be done via our department Integration Services.
Related to