Follow

API Version 1.0.4 Documentation

Version 1.0.4

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. 

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 

empty_returned: the container has been returned empty to the shipping line

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

 

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

[
{
"category": "string",
"event": "string",
"occurred_at": "2019-04-15T00:00:00Z",
"occurred_status": "string"
}
]

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", "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" } ] }

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments