Version 1.0.6
Version 1.0.6 adds por_arrival_time field to the container object to include the date and time that the container arrived at the place of receipt.
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. |
|
bill_of_lading |
BL12AF234 |
The bill of lading associated with the container. |
|
origin |
{ "locode" = "USOAK", "info" = "everport-oakland" "TZ" = "America/Los_Angeles" } |
The unlocode and textual representation of the port of origin including timezone |
|
port_of_loading |
{ "locode" = "USOAK", "info" = "everport-oakland" "TZ" = "America/Los_Angeles" } |
The unlocode and textual representation of the port including timezone 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" "TZ" = "America/Los_Angeles" } |
The unlocode and textual representation of the port of destination |
|
firms_code |
W778 |
The four character identifier of the facility in US Customs DB. |
|
return_text |
"USOAK" |
If applicable, the contextual information related to an container being returned empty |
|
returned_at |
"2016-10-30T12:34:56Z" |
If applicable, the date and time when the container was returned to the shipper. Otherwise the value is null |
|
pol_arrival_time |
"2016-9-1T12:34:56Z" |
If applicable, the date and time when the container arrived at the port of loading. Otherwise the value is null |
|
por_arrival_time |
"2016-9-1T12:34:56Z" |
If applicable, the date and time when the container arrived at the place of receipt. Otherwise the value is null |
The vessel object contains 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. |
|
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 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. |
|
unloccode |
"USOAK" |
The UN Location Code for the port |
Response
Your endpoint should respond with status 204 and an empty body.
The vessel object adds the following keys:
|
Key |
Example |
Description |
|
name |
"Burlingame Express" |
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 contains 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 |
|
lat_lng |
{"lat": 37.4224764 , "lng":-122.0842499} |
The latitude and longitude where the terminal is located |
Events
The container information contains an array of events with the following information:
|
Key |
Example/type |
Description |
|
category |
"lifecycle" |
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",
"returned_at": "2016-03-09 15:29:00",
"return_text": "OAKLAND, CA ,UNITED STATES",
"pol_arrival_time":"2016-02-02 13:35:00",
"por_arrival_time":"2016-02-02 13:35:00",
"origin": {
"locode": null,
"info": null
},
"port_of_loading": {
"locode": "DEHAM",
"info": "HAMBURG"
},
"destination": {
"locode": null,
"info": null
},
"tags": ["xmas", "urgent"]
},
"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",
"lat_lng": {
"lat": 37.4224764,
"lng":-122.0842499
}
},
"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"
}
]
}
Comments
0 comments
Please sign in to leave a comment.