简体

Overview

IQAX Shipment Tracking API provide trusted shipment tracking data with

1 Container events & route / vessel change with continuous ETA/ETD update of vessel schedule across carriers
2 Predictive ETA/ETD from proprietary machine learning model 30
3 Detected ATD & ATA from vessel AIS and advance geofencing technique
4 RESTful in conjunction with a Webhook method to access the update of shipment status via API

Additional Details:

Getting Started

Step 1

400

To get started, you must apply for a API subscription key from IQAX as each request to the interface requires a valid key to be provided.

If you’re interested but not yet have a API subscription key, you can book a demo to get things started.

Step 2

400

After acquiring subscription key, the first step will be to register the shipments into our system.

  • This can be done individually or as a batch if you have more than one shipment. In case you accidentally registered the wrong shipment, there will be a function to unregister this

  • Once the shipments are registered, you will be able to acquire the shipment data directly through the API ranging from basic information such as container size type all the way to shipment route and events.

  • From now, every call to the Shipment Tracking API will require an HTTP header Ocp-Apim-Subscription-Key with the value set to one of your subscription key, otherwise, unauthorized errors will result.

Try register shipment now.

Step 3

400

According to business needs, choose the main interfacing method by application requirement. Shipment Tracking API provides two kinds of interface, a RESTful API in conjunction with a Webhook API.

  • RESTful API is a traditional pull-based interface where users/applications can register or browse their shipments by firing HTTP requests.

More details of shipment tracking restful API now.

  • Webhook API requires customers to host a long-running server exposed to the internet, which will receive timely updates of shipment from Shipment Tracking API.

  • For security measure, pre-setup of your callback URL(s) is required before enabling the push services.

  • Once all the setup is ready, you can make use of webhook API to create shipment webhook subscription.

You need to register shipment with register shipment API before creating webhook subscription for push service.

More details of shipment tracking webhook API .

Supported Carriers

IQAX Shipment Tracking API supports a list of major Ocean Carriers, you will also need to provide carrierScac when you register a shipment for tracking.

Carrier Name (carrierSCAC)

  • ANL Container Line(ANNU)

  • CMA-CGM(CMDU)

  • CNC Line (CHNL)

  • COSCO (COSU)

  • CK Line (CKLU)

  • Evergreen (EGLV)

  • Hamburg Süd (SUDU)

  • Hapag-Lloyd(HLCU)

  • Heung-a (11QU)

  • Hyundai (HDMU)

  • KMTC (KMTC)

  • Maersk (MAEU)

  • MSC (MSCU)

  • Namsung (NSRU)

  • Ocean Network Express (ONEY)

  • OOCL (OOLU)

  • PIL (PABV)

  • Sealand (SEAU)

  • SINOKOR (SKLU)

  • TSLINE (13DF)

  • Wan Hai (WHLC)

  • Yang Ming (YMJA)

  • ZIM (ZIMU)
If you find any carrier which is important to your business but not yet supported, we could help to recommend different options according to your use cases. Please get in touch with us at customerservices@iqax.com.

By default, API provides "Unify" version, but it also offers an option to filter particular version(s) to fulfill your usecase.

Version Definition Param for version Recommend Scenarios

Unify

Return a combined version of booking carrier’s route and harmonized ETA (include predictive ETA) from ML model as well as detected ATA from AIS

UNI

Require most updated tracking data

Standard

Return raw route and events from booking carrier

STD

Require data from booking carrier only

Advance

Return enhanced route from multi sources and advanced event (like predictive ETA) from ML model

ADV

Require routing and ETA suggested by ML model

Default

Return Unify version

Not Specify

Choose between STD and ADV version for your usecase:

Consider the following scenario:

1 A shipment from Rotterdam to Al' Aqabah, booking carrier is indicating the container is travelling on CMA CGM VASCO DE GAMA with direct route in their website now.
2 Digital Twins consider schedule from multiple carriers and live vessel location, it detects CMA CGM VASCO DE GAMA is going to skip Al’ Aqabah. It suggests the container is going to T/S port in Jeddah and connect Al’ Aqabah with COSCO SHIPPING KILIMANJARO
Standard Version Advance Version

1000

1000

Always contains shipment route, container milestone and schedule from booking carrier at the moment

which may contain

1 Enriched shipment route and vessel recommendation ( e.g additional T/S port in Jeddah and vessel recommendation of COSCO SHIPPING KILIMANJARO in this example )
2 or Assoicate vessel schedule from multiple carriers which mentioned schedule for the schedule
3 or Predictive ETA/ETD

Supported Event

Event Model:
Event Code Description

MTY_PICKUP

Empty Container Picked Up

CNTR_RCVD

Full container Received by Carrier

CNTR_DEPARTURE

Container Depart from Facility

CNTR_ARRIVAL

Container Arrive at Facility

VSL_DEPARTURE

Vessel Departure

VSL_ARRIVAL

Vessel Arrival

CNTR_DISCHARGE

Discharged from Vessel

CNTR_PICKUP

Container to Consignee

CNTR_LOAD

Loaded on Board

CNTR_LOAD_ON_TRUCK

Loaded on Truck

CNTR_LOAD_ON_RAIL

Loaded on Rail

CNTR_LOAD_ON_BARGE

Loaded on Barge

CNTR_LOAD_ON_FEEDER

Loaded on Feeder

CNTR_DISCHARGE_FROM_TRUCK

Container Discharged from Truck

CNTR_DISCHARGE_FROM_RAIL

Container Discharged from Rail

CNTR_DISCHARGE_FROM_BARGE

Container Discharged from Barge

CNTR_DISCHARGE_FROM_FEEDER

Container Discharged from Feeder

MTY_RETURN

Empty Container Return to Depot

Shipment Registration API

Description:

The gateway endpoint to register shipment for tracking by ocean carrier SCAC code and booking / bill of lading number

Before performing queries, be reminded that each client is assigned a rate limit for calling all the APIs. Rate limiting is defined as below, which:
Allowed 500 requests per minute. When client performed too many requests, they will receive a HTTP 429 Too Many Requests error

Explore The APIs 30

1 Click "Servers", switch to a correct server, Trial/Normal depending on your subscription
2 Click "Authorize 🔒", paste your key (e.g. dr212fa991d84374bbp6f0cef8d2ab5c) to the field, then click "Authorize".
3 Select an API, click "Try it out", input parameters, then click "Execute".
Track and Trace Sandbox

Response Status

Details
Error (e.g 400 and 404) will return with a corresponding HTTP status code with the same response body signature, which usually explain themselves: 
{
    "message": "Error message",
    "status": "Response Status Code",
    "error": " Response Status "
}
Status Code Status Description

200

OK

400

Bad Request

The server could not understand the request due to invalid syntax. Usually it is parameter error, duplicate registration or business key conflict

401

Unauthorized

The request not be authorized.

500

Internal Server Error

The server has encountered a situation it does not know how to handle.

Error Code

Common Error Responses by Code:
Status Code Error Message

400

shipmentRegistrationCriteria:must not be blank

400

Unexpected error occurred, may be registration conflict. Please try again later.

400

Registration already exists.

400

JSON parse error: Unrecognized field \"xxxxxx\ ” xxxxx

400

Exceed the batch size, the registration data is only allowed up to 100

404

Can not find related registration with criteria.

400

Unexpected error occurred, may be registration conflict. Please try again later.

400

registrationFromDate and registrationToDate must not be null!

400

The shipment is not available for current booking number, please register with bl number for Maersk Group shipments.

400

Fail to register cause by request BL number different from existing BL number.

404

Registration not found.

400

page size must be between 1 and 100

400

page numbers must start at 0

Paging

Paging is available for Fetch All Shipment Registrations and Fetch Registrations Status
Default page = 0, and the page number starts from 0
Default size = 100, system accepting input between 1-100

Getting Status for Your Registration

You may query registration status by endpoint /shipment/registrations/registration-with-status above. Below are the detailed explanation of possible value for status and remark.

Status:
Status Description

PROCESSING

Registered shipment is do processing or keeping in re-trigger capture within time range.

READY TO TRACK

Registered shipment has result and ready to track

NO RESULT

Registered shipment cannot be found from carrier

INCOMPLETE

Shipment are found from carrier but with incomplete information. Check Remark for details, system will automatically retry for 7 days.

ERROR

Failed to register shipment. Check Remark for details.
Remark:
Remark Description

MISSING CONTAINER SLOT

Returned result does not contain any containers

ALL CONTAINERS MISSING OCEAN LEG

The shipment route information is unavailable for all containers

SOME CONTAINERS MISSING OCEAN LEG

The shipment route information is unavailable for some containers

REGISTERED CONTAINER NOT IN CAPTURE RESULT

Registered container is not found from the returned result

REGISTERED CONTAINER MISSING OCEAN LEG

The shipment route information is unavailable for the registered container

REGISTERED SHIPMENT ENCOUNTERED ISSUE WHEN FETCHING DATA

System will automatically retry for 7 days and set "No result" in "Status".

SCAC CODE NOT DEFINED IN CUSTOMER PROFILE

Unsupported carrierSCAC code is in used.

Registration Scenarios (By Shipment)

IQAX Shipment Registration API simplifies the whole registration flow. This API allowing you register or update BL by controlling the call sequence and input params, consider below scenarios for more details:

Details
Case Step API used Objective BC as Param BL as Param Quota Reduction Remark

1

1

Register

Register BC

bc1

1

2

Register

Update BC with BL

bc1

bl1

0

2

1

Register

Register BC

bc1

1

2

Register

Update BC with BL

bc1

bl1

0

3

Register

Register BL

bl1

1

3

1

Register

Register BC

bc1

1

2

Register

Update BC with BL

bc1

bl1

0

3

Unregister

Unregister BC

bc1

Auto unregister bl1 as well

4

1

Register

Register BC

bc1

1

2

Register

Register BL

bl1

1

3

Register

Update BC with BL

bc1

bl1

0

4

Unregister

Unregister BC

bc1

bl1 still be active due to step 2

5

1

Register

Register BC

bc1

1

2

Register

Update BC with BL

bc1

bl1

0

3

Unregister

Unregister BC

bc1

Auto unregister bl1 as well

4

Register

Recover BC

bc1

0

Auto supplement bl1

6

1

Register

Register BC

bc1

1

2

Register

Register BL

bc1

bl1

0

3

Register

Update BC with BL

bl1

0

4

Unregister

Unregister BC

bc1

bl1 still be active due to step 2

4

Register

Recover BC

bc1

0

Auto supplement bl1

7

1

Register

Register BC

bc1

1

2

Register

Register BL

bl1

0

3

Register

Update BC with BL

bc1

bl1

0

4

Unregister

Unregister BL

bl1

only unsubscribe step2
BL number cannot be changed once it is associated with BC

Shipment Tracking Restful API

Description:

The gateway endpoint returns the shipment tracking result by carrier SCAC code together with either booking / bill of lading number [and container number].

Before performing queries, be reminded that each client is assigned a rate limit for calling all the APIs. Rate limiting is defined as below, which:
Allowed 500 requests per minute. When client performed too many requests, they will receive a HTTP 429 Too Many Requests error

Explore The APIs 30

1 Click "Servers", switch to a correct server, Trial/Normal depending on your subscription
2 Click "Authorize 🔒", paste your key (e.g. dr212fa991d84374bbp6f0cef8d2ab5c) to the field, then click "Authorize".
3 Select an API, click "Try it out", input parameters, then click "Execute".
Track and Trace Sandbox
When event timestamp as 00:00:00 and GMT as null , it refers to the case which the local time is not available.

Example

"pointSequence": 1,
"eventCode": "MTY_PICKUP",
"eventDescription": "Empty equipment dispatched",
"eventStatus": "ACTUAL",
"eventDT": {
	"locDT": "2023-03-17T00:00:00" ,
	"timeZone": "Europe/Amsterdam",
	"GMT": "null"
}

Response Status

Details
Error (e.g 400 and 404) will return with a corresponding HTTP status code with the same response body signature, which usually explain themselves: 
{
    "message": "Error message",
    "status": "Response Status Code",
    "error": " Response Status "
}
Status Code Status Description

200

OK

204

No Content

Registration record is found but no result yet.

400

Bad Request

The server could not understand the request due to invalid syntax. Usually it is parameter error, duplicate registration or business key conflict

401

Unauthorized

The request not be authorized.

404

Not Found

Shipment Registration is not found.

500

Internal Server Error

The server has encountered a situation it does not know how to handle.

Error Code

Common Error Responses by Code:
Status Code Error Message

400

JSON parse error: Unrecognized field \"xxxxxx\ ” xxxxx

404

Can not find related registration with criteria.

404

Registration not found.

Shipment Tracking Webhook API

For security measure, a pre-setup of your callback URL(s) is required to enable the push services, Please contact us by customerservices@iqax.com before you plan to start the connectivity test.

Explore The APIs 30

1 Click "Servers", switch to a correct server, Trial/Normal depending on your subscription
2 Click "Authorize 🔒", paste your key (e.g. dr212fa991d84374bbp6f0cef8d2ab5c) to the field, then click "Authorize".
3 Select an API, click "Try it out", input parameters, then click "Execute".
Track and Trace Sandbox
When event timestamp as 00:00:00 and GMT as null , it refers to the case which the local time is not available.

Example

"pointSequence": 1,
"eventCode": "MTY_PICKUP",
"eventDescription": "Empty equipment dispatched",
"eventStatus": "ACTUAL",
"eventDT": {
	"locDT": "2023-03-17T00:00:00" ,
	"timeZone": "Europe/Amsterdam",
	"GMT": "null"
}

Response Status

Details
Error (e.g 400 and 404) will return with a corresponding HTTP status code with the same response body signature, which usually explain themselves: 
{
    "message": "Error message",
    "status": "Response Status Code",
    "error": " Response Status "
}
Status Code Status Description

200

OK

400

Bad Request

The server could not understand the request due to invalid syntax. Usually it is parameter error, duplicate registration or business key conflict

401

Unauthorized

The request not be authorized.

404

Not Found

Shipment Registration is not found.

500

Internal Server Error

The server has encountered a situation it does not know how to handle.

Error Code

Common Error Responses by Code:
Status Code Error Message

400

shipmentWebhookCriteria:must not be blank

400

Webhook already exists.

400

The callback URL is not valid.

400

Failed to connect callback endpoint: error on post request for +webhook.getCallbackURL()

400

Failed to connect callback endpoint: cannot get response with 2xx successful or 400 bad request.

400

Inconsistent with the registered secret.

400

JSON parse error: Unrecognized field \"xxxxxx\ ” xxxxx

404

Can not find related subscription with criteria.

404

Registration not found.

Action Status

Shipment updated events are detected Route and Event change. Action Type will be indicted as: NEW / UPDATE / DELETE for Event changes and UPDATE for Route changes.

Action Description

UPDATE

Updated event/route/message

NEW

New event/message

DELETE

Deleted event
A full set message will be pushed to Webhook client server once captured result is available after shipment registration. Action Type at the first time will be indicated as "NEW", on-going update will be marked as "UPDATE".
The Webhook client server should only return HTTP status code 200 to indicate a successful reception. Other responses will be regarded as failures.

Client Server Verification and Confirmation

Upon the creation of a Webhook, the API server will immediately fire an event callback to the designated URL with no events (i.e., the request body is []), client server should return HTTP code 200 as to confirm and verify a healthy connection for both parties. Otherwise this endpoint will fail.

  • Before fire event to client server, the API server will use sha1 and sha256 to encrypt the secret if the webhook registration includes secret.

  • The API server will pass the encrypted secret when callback to the designated URL, if the client server validates the encrypted secret, then return 200 to let the API server know the Webhook is already established.

Shipment Updated Event Timing

Only when shipment route/event change happens with a Webhook enabled, the change will be regarded as an event pending to be sent. There is no way to get notified when shipment route/event is updated without any available Webhook connection.

Error and Recovery

Events that happen while the Webhook is disabled will not be actively pushed to the client, even when client recovers and recreate the Webhook.
Clients could use the RESTful API to retrieve all shipments to maintain their data, but no event history could be provided.

Security

A web server exposed to the public internet that can respond to Webhook calls correctly is required to establish a working Webhook. Since the client server prone to attacks, following the security measures is strongly advised.

You are recommended to whitelist our server IP addresses while denying all external request to prevent potentially harmful threats or inappropriate access to your server. Please contact us by customerservices@iqax.com if you have applied this cybersecurity strategy for our IP segments.
Webhook creation requires an HTTPS callback endpoint, this is done to prevent leakage of information throughout the network channel.

Integrity Verification

As clients are exposed to the internet, malicious calls may reach clients' server, the secret key attached in the Webhook callback’s X-DHST-Signature and X-DHST-Signature-256 header, and can be used to ensure the caller’s identity, the integrity of the payload and prevent replay attacks.

Example:

1 Client server received webhook POST request at registered URI with header X-DHST-Signature-256: 4F89C033B5EE1A094B6F16B5F315FE7CE180FD1512D9AB031848472E150095C0
2 Client server previously subscribe webhook with secret key (from /webhook/shipment APIs 's secret field): api_token
3 Client server MUST verify that the DHST-Signature-256 in header should be same as encrypted secret, otherwise it’s highly likely to receive malicious requests.
4 https://en.wikipedia.org/wiki/SHA-2 have an introduction about the principles of encryption.