In this article, we provide advice on how to implement the API of Cargo Controller Export in your own system. Make sure you don’t miss out on 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 can see 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 carried out.
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 latest known status (state) of your cargo. In addition, Portbase also sends the event payload containing only the differences compared to the latest information. It is up to your organisation to determine, 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 vessel and 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 via other routes. You will find more about this later in this article.
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, or the booking number with vessel information (IMO or CRN). By adding the IMO or CRN next to the booking number, Premium Terminal Data (add-on for Cargo Controller) can also be shared.
Response:
When you track a booking, a unique ID is registered and included in the response. Advice: 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 available. This message shares the latest known status (state) of the cargo. In addition, Portbase also sends the event payload containing only the differences compared to the latest information.
In the image below, you can see a schematic representation of the explanation above.
Web interface
In the web interface, a booking number can be added manually; the booking number can optionally be supplemented with vessel information by selecting the vessel. Cargo information for a booking tracked in the web interface is also automatically 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. At 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 for yourself whether you store the bookings in your system. The current full status of the cargo is shared. In this message, the latest known status (state) of the cargo is shared. In addition, Portbase also sends the event payload containing only the differences compared to the latest information.
In the image below, you can 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 forwarded to Cargo Controller Export. By default, automatic forwarding is enabled; the main administrator can disable this. Cargo information in Cargo Controller Export in the web interface is also automatically 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 forwarded 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. At 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 for yourself whether you store the bookings in your system. The current full status of the cargo is shared. In this message, the latest known status (state) of the cargo is shared. In addition, Portbase also sends the event payload containing only the differences compared to the latest information.
In the image below, you can see a schematic representation of the explanation above.
Customer system offline - added subscription
If your system goes offline, there is an option to request the latest status. You can read the explanation per flow below.
GET:
There is an option to request the final status again using the SubscriptionID.
Response:
Updates are shared when available. This message shares the latest known status (state) of the cargo. In addition, Portbase also sends the event payload containing only the differences compared to the latest information.
In the image below, you can 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. We expect a response to this update within 5 seconds. If we do not receive a response, the update will then be sent 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 described above.
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