First read the ‘About this API’ section of the Cargo Controller API specs before you can continue.
Track your Cargo (happy flow)
When you track a B/L, a unique id is registered and will be provided in the response. Please be aware that any B/L tracked by your organisation will result in a transaction fee, also when the B/L appears non-existent.
Example for non-existent B/L: When an agent splits the B/L, this will result in two new B/L ‘s. Both new B/L’s needs to be tracked to receive updates. The former B/L number will become non-existent.
Advice: The id in the response must be registered within your own system as we will provide this id as identifier in all future updates on your B/L. We will demand this id also when you need to nominate or authorise a party for a transport equipment.
Alternative flow Tracking a B/L from Cargo Controller web interface will also result in a webhook update with a unique id. This id is probably not recognised by your system. You can decide whether to store these B/L's in your system. B/L's tracked from Cargo Controller web can be identified by its origin: WEB.
API operation: Track requests
Track your Cargo (not yet known in Portbase)
API operation: Track requests
Track your Cargo (not yet known in client system)
API operation: Track requests
In 2 scenarios you can be confronted with a unknown TrackID and B/L:
- A webuser tracks a B/L manually that is not tracked previously via the API. This will result in a webhook event towards your webhook, with a B/L and a unknown TrackID for your administration.
- An external organisation has authorized your organisation to a B/L within the Secure Chain and that was not tracked previously via the API by your organisation. This will result in a webhook event towards your webhook, with a B/L and an unknown TrackID for your administration.
Note: In both cases you will need to create a queue which collects these B/L’s and TrackID’s for further processing. This to maintain in sync with all tracked B/L’s in Cargo Controller.
Basic or Extended tracking
When you submit a track request via API or web (see scenario 1) we will define this as a 'Extended' track request, we will charge this track request as a paid transaction.
When you receive a track request via webhook that you didn't tracked before, we will define this as 'Basic tracking', we will charge this track request as a free transaction. With 'Basic tracking' you will receive a limited amount of information, but sufficient information to proceed your mandatory actions that is necessary for the Secure Chain (i.e. Authorise or Nominate parties). For more information read our FAQ.
Upgrade tracking
When you decide that 'Basic tracking' isn't sufficient for your operations, you can create a track request for this B/L via API. We will upgrade the tracking to an 'Extended tracking' and our response towards your webhook will contain all information as usual. We will charge this track request as a paid transaction.
Get Tracked B/L (only after client downtime)
API operation: Tracked B/L's
Implementation advice (time-outs)
API operation: Webhook events
When you receive a webhook event on a tracked B/L, we push these updates with our TrackID. On this update we expect a response within 30 seconds. We will try to push our updates 3 times, within a total time frame of 90 seconds.
When our third attempt will not be answered with the 30 second window, we will trigger our time-out notification e-mail towards your IT department or software supplier. From Portbase point of view we cannot reach your webhook(s).
Our advice on setting up the update process concerning our webhook events would be as follows:
