Purpose
The Cargobase tracking update end-point is available only to Provider companies for the purpose of posting tracking updates to Cargobase. This end-point allows a provider to post tracking events onto a shipment. At this moment, all events are posted 'as-is'.
Access
A provider can only post tracking updates for shipments associated with their account. POSTS for other shipments will be rejected.
An access token is required to POST to this end-point. Contact [email protected] to obtain your token.
Request URI
POST https://pluto.cargobase.com/api/1/tracking/
Content-Type: application/json
Authorization: Token 'your_token_here'Message body definition
| POST parameter | Value | Required |
|---|---|---|
| primary_tracking_number | STRING - tracking number as published to Cargobase | Yes |
| event | STRING your event | Yes |
| event_type | STRING of the event category, limited options available see below | No |
| event_timestamp | YYYY-MM-DDTHH:MM:SS | No |
Event types
Event types are used to categorise your updates. You do not need to send an event-type, however if you do it has to be one of the following categories.
| event_type | description |
|---|---|
| InfoReceived | (default value, if none is provided) |
| InTransit | to share the in transit status of a shipment. In future, this will be used to update the 'status' of an actual shipment from 'Booked' too 'In Transit'. |
| OutForDelivery | to identify that your shipment will be delivered shortly. This will be used to send 'ad-hoc' notifications to the consignee. |
| Exception | to identify an exception on the shipment. This is used to send additional notifications to the manager of the shipment. |
| Delivered | Submit this event_type to close the shipment, does require additional details, see below. |
Event type Delivered
The delivered event type is used to trigger the closure workflow in the platform. Closure, is only possible after shipment delivery, therefore it is required to include an acceptor and pod_timestamp in your body message, see the sample below.
An additional event description via the 'event' parameter is not required.
event_timestamp
You can include a timestamp for the events that you post. These timestamps are reflected on the platform. If you choose to include a timestamp, ensure you follow this format: YYYY-MM-DDTHH:MM:SS. Timestamp are displayed on the platform as ; YYYY-MM-DD HH:MM
Message body sample
Regular update
{
"primary_tracking_number": "Your tracking number",
"event": "This is the body message of your update",
"event_type": "InTransit",
"event_timestamp": "2019-04-11T09:00:00"
}Delivered Shipment update/Submit POD
{
"primary_tracking_number": "Your tracking number",
"event_type": "Delivered",
"acceptor":"Name of recipient",
"pod_timestamp": "2019-05-28T09:00:00"
}Status codes
| Status | Description | Resolution |
|---|---|---|
| 201 | Post received | -- |
| 304 | Data missing | Check if all mandatory fields are present |
| 400 | Bad Request | Check data types and event_type category |
| 403 | Forbidden | check Authentication credentials |
| 415 | Unsupported media type | Add Content-Type: application/json |
Status code 201
Status code 201 signifies that the message is well received, and a confirmation number is provided in the response
{
"success": "The update was posted on the shipment with tracking number: your_tracking_number"
}