Version 1.0.0
Authentication
Every user-initiated request needs to have a valid Authorization header. The value of the header must be Token token="XXX", where XXX is the user token. See examples below.
REST endpoints
The following endpoints are available:
POST /api/v1/containers
Add a container to your dashboard, which will cause webhooks to be invoked whenever updated information is available about the container.
Request
The request body must be a JSON object of the form {"container": < container-object >, "sandbox_url": "webhook url"}, where < container-object > has the following structure:
|
Key |
Required? |
Value |
|
number |
required |
The container number, e.g. GESU1234567 |
|
pod |
optional |
The port of discharge. If provided, this must be a valid 5-character uppercase port code, e.g. USTIW |
|
vessel_voyage |
optional |
The vessel name and voyage number, e.g. DUESSELDORF EXPRESS 06W31 |
|
shipping_line |
optional |
The shipping line scac, e.g. MAEU for Maersk |
|
tags |
optional |
An array of tags that will be saved to the container, e.g. ["foo", "bar"] |
sandbox_url is an optional webhook url that can be different than the organization's webhook url. If included, the api will immediately invoke the webhook with fake information after sending the response. Please see below for the format of the webhook request.
Response
On success, the API may respond with a status of 200 OK or 204 No Content. On failure, the API will return:
|
Status |
Reason |
Body |
|
400 |
Missing container number |
{"errors": ["Container number is required"]} |
|
400 |
Invalid container number |
{"errors": ["Container number is invalid"]} |
|
400 |
Invalid port of discharge |
{"errors": ["Port of discharge is invalid"]} |
Example
curl -X POST \
-H 'Authorization: Token token="XXX"' \
-H 'Content-type: application/json' \
-d '{"container": {"number": "XYZZ1234567", "pod": "USTIW", "vessel_voyage": "DUESSELDORF EXPRESS 06W31"}}' \
https://track.cruxsystems.com/api/v1/containers
Webhooks
Outbound webhooks are sent to your application.
Container event webhook
The container event webhook is fired via HTTP POST whenever updated information is available for one of the containers on your dashboard.
Immediately after adding a container to your dashboard, Crux Systems will begin searching for your container and invoke the webhook with event type created. Afterwards, every time the container's status is updated, Crux Systems will invoke your webhook with the event type updated.
If the webhook URL is over HTTPS, an Authorization header will be included. The value of the header will be Token token=”XXX”, where XXX is the user token.
Request
The request body is a JSON object with the following keys:
|
Key |
Description |
|
event_type |
Either created (the first time the container is searched) or updated |
|
container |
The container status (see below) |
|
vessel |
Metadata about the vessel (see below) |
|
terminal |
Metadata about the terminal (see below) |
The container object contains the following keys:
|
Key |
Example |
Description |
|
number |
GESU1234567 |
The container number. |
|
status |
"available" |
One of: not_manifested: the container that is so early in its lifecycle that the terminal doesn't know about it yet en_route: the container has not yet arrived at the import terminal on_ship: the container is on a vessel and is headed to its destination, or waiting to be unloaded at a terminal not_available: the container is in yard, but not yet available, at the import terminal available: the container is in yard and available at the import terminal departed_terminal: the container has departed from the terminal at the port of discharge |
|
departed_at |
"2016-10-29T12:34:56Z" |
If applicable, the date and time when the container departed the terminal. Otherwise the value is null. |
|
discharged_at |
"2016-10-30T12:34:56Z" |
If applicable, the date and time when the container was discharged. Otherwise the value is null. |
|
location |
"In Yard (#B004 row) Grounded" |
If applicable, the location of the container within the terminal. |
|
demurrage |
"240.00" |
If applicable, the demurrage amount in USD. Otherwise the value is null. |
|
last_free_day |
"2016-10-31" |
If applicable, the last free day of the container. Otherwise the value is null. Dates are listed in the same timezone as the terminal. |
|
line_hold |
"RELEASED" |
The reason for the line hold if the container is subject to a line hold. If all line holds have been released, it has the value "RELEASED". If the hold state is not yet known, the value is null. |
|
customs_hold |
"RELEASED" |
The reason for the customs hold if the container is subject to a customs hold. If all customs holds have been released, it has the value "RELEASED". If the hold state is not yet known, the value is null. |
|
other_holds |
null |
Any other holds on the container. If there are no miscellaneous holds, the value is null. |
|
tags |
[ "foo", "bar" ] |
An array of tags that are saved on the container. |
The vessel object containers the following keys:
|
Key |
Example |
Description |
|
name |
MSC NILGUN |
If applicable, the name of the vessel. Otherwise the value is null. |
|
eta |
"2016-10-29T12:34:56Z" |
If applicable, the ETA of the vessel. Otherwise the value is null. ETAs are listed in UTC. An ETA update is provided via the API when there is another status update to report on the container. |
|
ata |
"2016-10-29T12:34:56Z" |
If applicable, the ATA of the vessel. Otherwise the value is null. |
The terminal object contains the following keys:
|
Key |
Example |
Description |
|
name |
Maher Elizabeth |
The name of the terminal. |
|
timezone |
America/New_York |
The Olson TZID for the timezone of the terminal and vessel. |
Here is a sample webhook request:
{
"event_type": "updated",
"container": {
"number": "XYZZ1234567",
"status": "available",
"discharged_at": "2016-05-06T22:08:00Z",
"last_free_day": "2016-05-13",
"departed_at": null,
"location": "In Yard (#B003 row) Grounded",
"demurrage": "0.00",
"line_hold": "RELEASED",
"customs_hold": "RELEASED",
"other_holds": null
},
"vessel": {
"name": "ZIM TEXAS",
"eta": "2016-05-06T14:00:00Z",
"ata": "2016-05-06T14:00:00Z"
},
"terminal": {
"name": "POHA Bayport Houston",
"timezone": "America/Chicago"
}
}
Response
Your endpoint should respond with status 204 and an empty body.
Version 1.0.1 Updates
Webhooks
In addition to the attributes available in version 1.0.0, the following attributes will be transmitted. Note that these attributes may be null if the data sources that originate the events do not provide enough information to infer the attributes.
Container Object
|
Key |
Example |
Description |
|
bill_of_lading |
BL12AF234 |
The bill of lading associated with the container. |
|
origin |
{ "locode" = "USOAK", "info" = "everport-oakland" } |
The unlocode and textual representation of the port of origin |
|
port_of_loading |
{ "locode" = "USOAK", "info" = "everport-oakland" } |
The unlocode and textual representation of the port where the container was last loaded into the vessel (i.e. different from the origin in case of trans-shipment |
|
destination |
{ "locode" = "USOAK", "info" = "everport-oakland" } |
The unlocode and textual representation of the port of destination |
Version 1.0.2 Updates:
Webhooks
In addition to the attributes available in version 1.0.1, the following attributes will be transmitted. Note that these attributes may be null if the data sources that originate the events do not provide enough information to reliably infer it.
General:
|
Key |
Example |
Description |
|
as_of |
"2016-10-29T12:34:56Z" |
A timestamp of when the information of the event is obtained. The value is either the timestamp provided by the data source, or the timestamp of when the information is available to Crux Systems if the data sources do not provide a reliable value. |
Container Object:
|
Key |
Example |
Description |
|
firms_code |
W778 |
The four character identifier of the facility in US Customs DB. |
|
origin |
{ "locode" = "USOAK", "info" = "everport-oakland" "TZ" = "America/Los_Angeles" } |
Adding the timezone name according to iana.org of the port of origin. |
|
port_of_loading |
{ "locode" = "USOAK", "info" = "everport-oakland" "TZ" = "America/Los_Angeles" } |
Adding the timezone name according to iana.org of the last port of loading. |
|
destination |
{ "locode" = "USOAK", "info" = "everport-oakland" "TZ" = "America/Los_Angeles" } |
Adding the timezone name according to iana.org of the port of destination. |
|
events |
[ |
An array of events associated with the container. The category indicates whether the event is a container lifecycle or a workflow (user generated events). Initially only lifecycle events will be reported. The event describes what action or state change affected the container. "Occurred at" provides the timestamp of when the event occurred. "Occurred_status": defines whether the event is estimated (to happen in the future) or actual (already past). |
The vessel object adds the following keys:
|
Key |
Example |
Description |
|
name |
<> |
The vessel name |
|
eta |
2016-06-05T00:00:00Z |
Estimated time of arrival |
|
ata |
2016-06-05T00:00:00Z |
Actual time of arrival |
Terminal Object
The terminal object adds the following keys:
|
Key |
Example |
Description |
|
name |
Maher Elizabeth |
The name of the terminal |
|
unloccode |
USOAK |
The UN Location Code for the port |
|
timezone |
America/Los Angeles |
The timezone where the terminal is located |
Events
The information also contains an array of events with the following information:
|
Key |
Example/type |
Description |
|
category |
lifecycle, workflow |
The type of event, either lifecycle or workflow events |
|
event |
lifecycle_discharge |
The event that the shipment experienced |
|
location_locode |
THLCH |
The locode where the event took place if available |
|
location_terminal_cruxid |
<alpha-numerical> |
A unique identifier of the terminal where the event took place, if available |
|
location_text |
Burlingame, USA |
A text description of the location where the event took place, if available |
|
occurred_at |
timestamp |
Timestamp of when the event takes place |
|
occurred_date |
date |
Calendar day when the event takes place |
|
occurred_status |
actual or estimate |
Whether the event occurred in the past (actual) or it is estimated it will occur in the future (estimate) |
|
occurred_time |
time |
Time when the event takes place |
|
transit_mode |
rail, ship, truck |
The transportation mode that generated the event if applicable |
|
transit_scac |
SCAC |
SCAC code for the transportation mode |
|
transit_text |
text |
Textual representation of the transportation mode |
|
transit_vessel_imo |
IMO number |
IMO of the vessel if applicable |
Example
A full example of the information provided:
{
"event_type": "updated",
"container": {
"number": "ACLU9789590",
"status": "available",
"discharged_at": "2019-04-20T20:18:04Z",
"last_free_day": "2019-04-27",
"departed_at": null,
"location": "YARD",
"demurrage": 0,
"line_hold": "RELEASED",
"customs_hold": "RELEASED",
"other_holds": "",
"bill_of_lading": "SA00373466",
"firms_code": "S787",
"origin": {
"locode": null,
"info": null
},
"port_of_loading": {
"locode": "DEHAM",
"info": "HAMBURG"
},
"destination": {
"locode": null,
"info": null
},
"tags": []
},
"vessel": {
"name": "CHARLESTON EXPRESS",
"eta": "2019-04-19T08:00:00Z",
"ata": "2019-04-19T10:36:00Z"
},
"terminal": {
"name": "POHA Barbours Cut Houston",
"locode": "USHOU",
"timezone": "America/Chicago"
},
"events": [
{
"category": "lifecycle",
"event": "lifecycle_discharge",
"location_locode": "USHOU",
"location_terminal_cruxid": "USHOU-BCT",
"location_text": "HOUSTON",
"location_time_zone": "America/Chicago",
"occurred_at": "2019-04-20T20:18:04Z",
"occurred_date": "2019-04-20",
"occurred_status": "actual",
"occurred_time": "15:18:04",
"transit_mode": "ship",
"transit_scac": "ACLU",
"transit_text": "CNE-067E",
"transit_vessel_imo": "9243162"
},
{
"category": "lifecycle",
"event": "lifecycle_arrival",
"location_locode": "USHOU",
"location_terminal_cruxid": null,
"location_text": "HOUSTON",
"location_time_zone": "America/Chicago",
"occurred_at": "2019-04-19T14:06:00Z",
"occurred_date": "2019-04-19",
"occurred_status": "estimated",
"occurred_time": "09:06:00",
"transit_mode": "ship",
"transit_scac": "ACLU",
"transit_text": "CHARLESTON EXPRESS ",
"transit_vessel_imo": "9243162"
}
]
}
Version 1.0.3 Updates
Version 1.0.3 only adds the information of the nominal longitude and latitude of the terminal object in the notification with fields called "longitude" and "latitude" respectively:
"terminal": {
"name": "POHA Barbours Cut Houston",
"locode": "USHOU",
"timezone": "America/Chicago",
"longitude": 37.4224764,
"latitude": -122.0842499
}
Version 1.0.4 Updates
Version 1.0.4 adds "return_text" and "returned_at" fields to the container object to describe the contextual information around a container that has been returned empty. A full description of the version can be seen here: API Version 1.0.4 Documentation
Comments
0 comments
Please sign in to leave a comment.