English

概述

和易孚追箱易接口提供可信的货运跟踪数据, 包括

1 集装箱动态和航线/船舶变更，以及持续提供跨承运人的船期 (ETA/ETD) 更新
2 提供来自专有机器学习模型的预测 ETA/ETD 30
3 从船舶 AIS 和先进的地理围栏技术中检测到 ATD 和 ATA
4 通过"查询"及"订阅"方法获得集装箱状态更新

参考:

和易孚追箱易接口会不定期更新，以确保提供准确的数据和优质的服务。 点阅查看最近更新。

入门

步骤1

400

要开始使用，您必须从和易孚申请接口订阅密钥，因为对接口的每个请求都需要提供有效的密钥。

如果您有兴趣但还没有接口订阅密钥，您可以先 注册户口， 然后 申请试用

步骤 2

400

获取订阅密钥后，第一步是将"订阅号"（提单号或订舱号）注册到我们的系统中。

  • 登记"订阅号"后，您可以直接通过API获取数据，包括集装箱基本信息及动态，以及航线/船舶或船期(ETA/ETD)更新 。

  • 从现在开始，对和易孚追箱易接口的每次调用都需要一个 HTTP 请求头 Ocp-Apim-Subscription-Key，其值设置为您的订阅密钥之一，否则将导致未经授权的错误。

更多详细信息 注册"订阅号" .

Step 3

400

注册提单号或订舱号後，我们需要一点时间获取资讯。请耐心等候

  • 您可以使用注册"订阅号" 的接口 /shipment/registrations/registration-with-status 来查询注册状况。

  • 当状态码为"Ready to Track"时，表示该订阅号讯息已获取。详细请参照 订阅号状态

步骤 4

400

根据业务需要，根据应用需求选择主要的接口方式。和易孚追箱易提供两种接口，"查询"及"订阅"。

  • "查询" 接口是一个传统的基于拉取的接口，用户/应用程序可以通过HTTP 请求来注册或获取数据。

立即尝试 追箱易查询接口 .

  • "订阅" 用户需要提供接收主动推送的URL，该服务器将及时接收来自和易孚追箱易接口的信息更新。

  • 为了安全考虑，在启用"订阅"服务之前需要预先设置您的回调地址。

  • 当所有设置准备就绪，您就可以使用订阅接口来订阅推送服务。

在订阅推送服务之前，您需要先使用注册接口 注册shipment。

更多详细信息 追箱易订阅接口 .

注册接口

细节:

通过 承运人 carrSCAC 和 "订舱/提单号" 注册以获得跟踪数据:

在执行查询之前，每个客户请注意所有接口端点有调用的速率限制。速率限制定义如下，其中：
每分钟允许 500 个请求。当客户端执行太多请求时，他们将收到 HTTP 429 Too Many Requests 错误。

探索 接口 30

1 单击“Authorize 🔒”，将您的密钥（例如 dr212fa991d84374bbp6f0cef8d2ab5c）粘贴到该字段，然后单击“Authorize”。
2 选择一个API，点击“Try it out”，输入参数，然后点击“Execute”。
Track and Trace Sandbox

返回状态

细节
错误（例如 400 和 404）将返回具相应 HTTP 状态代码，通常会自行解释： 

  
1
2
3
4
5


  
{
    "message": "Error message",
    "status": "Response Status Code",
    "error": " Response Status "
}
状态码 状态 描述

200

OK

400

Bad Request

由于语法无效，服务器无法理解请求。通常是参数错误、重复注册或业务密钥冲突

401

Unauthorized

该请求未被授权。

500

Internal Server Error

服务器遇到了不知道如何处理的情况。

错误代码

常见的错误代码:
状态码 错误信息 解释

400

shipmentRegistrationCriteria:must not be blank

shippingRegistrationCriteria: 不能为空

400

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

发生意外错误，可能是注册冲突。请稍后再试。

400

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

JSON解析错误：无法识别的字段\“xxxxxx\” xxxxx

400

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

超过批量大小，注册数据最多只允许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!

registrationFromDate 和registrationToDate 不能为空！

400

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

该货件不适用于当前的订舱号，士基集团的货件 请使用 提单号注册。

404

Registration not found.

未找到注册。

400

page size must be between 1 and 100

页面大小必须在 1 到 100 之间

400

page numbers must start at 0

页码必须从 0 开始

订阅号状态

你可以透过上述接口 /shipment/registrations/registration-with-status 查詢订阅号状态。以下是状态解释。

状态:
状态 解释

PROCESSING

处理中

READY TO TRACK

资讯已获取并可查询

NO RESULT

找不到相关订阅号

INCOMPLETE

运营商处的资讯不齐全。原因请查看描述，系统会于一星期内多次重试

ERROR

获取资讯失败。 原因请查看描述.
描述:
描述 解释

MISSING CONTAINER SLOT

返回资讯没有箱号

ALL CONTAINERS MISSING OCEAN LEG

所有集装箱没有航线信息

SOME CONTAINERS MISSING OCEAN LEG

部份集装箱没有航线信息

REGISTERED CONTAINER NOT IN CAPTURE RESULT

订阅箱号不在返回资讯中

REGISTERED CONTAINER MISSING OCEAN LEG

订阅箱号没有航线信息

REGISTERED SHIPMENT ENCOUNTERED ISSUE WHEN FETCHING DATA

资讯获取发生问题。系统会于一星期内多次重试，如仍不能，会返回状态 "NO RESULT"

SCAC CODE NOT DEFINED IN CUSTOMER PROFILE

系统不支持该carrierSCAC code

页面

分页可用于 Fetch All Shipment Registrations 和 Fetch Registrations Status
默认page = 0，页码从0开始
默认大小 = 100，系统接受 1-100 之间的输入

追箱易查询接口

细节:

通过 承运人 carrSCAC 和 "订舱/提单号" 从端点返回跟踪数据。

在执行查询之前，每个客户请注意所有接口端点有调用的速率限制。速率限制定义如下，其中：
每分钟允许 500 个请求。当客户端执行太多请求时，他们将收到 HTTP 429 Too Many Requests 错误。

探索 接口 30

1 单击“Authorize 🔒”，将您的密钥（例如 dr212fa991d84374bbp6f0cef8d2ab5c）粘贴到该字段，然后单击“Authorize”。
2 选择一个API，点击“Try it out”，输入参数，然后点击“Execute”。
Track and Trace Sandbox
当未能提供事件的本地时间时,动态的本地时间戳为 00:00:00 且 GMT 为 null 。

例子


  
1
2
3
4
5
6
7
8
9


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

返回状态

细节
错误（例如 400 和 404）将返回具相应 HTTP 状态代码，通常会自行解释： 

  
1
2
3
4
5


  
{
    "message": "Error message",
    "status": "Response Status Code",
    "error": " Response Status "
}
状态码 状态 描述

200

OK

204

No Content

已找到注册记录，但还没有结果。

400

Bad Request

由于语法无效，服务器无法理解请求。通常是参数错误、重复注册或业务密钥冲突

401

Unauthorized

该请求未被授权。

404

Not Found

未找到注册记录登记。

500

Internal Server Error

服务器遇到了不知道如何处理的情况。

错误代码

常见的错误代码:
状态码 错误信息

描述

400

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

JSON解析错误：无法识别的字段\“xxxxxx\” xxxxx

404

Can not find related registration with criteria.

找不到符合条件的相关注册。

404

Registration not found.

未找到注册。

追箱易订阅接口

出于安全考虑，您需要预先设置 回调地址 以启用推送服务，在您计划开始连接测试之前 ，请通过customerservices@iqax.com联系我们。

探索 接口 30

1 单击“Authorize 🔒”，将您的密钥（例如 dr212fa991d84374bbp6f0cef8d2ab5c）粘贴到该字段，然后单击“Authorize”。
2 选择一个API，点击“Try it out”，输入参数，然后点击“Execute”。
Track and Trace Sandbox
当未能提供事件的本地时间时,动态的本地时间戳为 00:00:00 且 GMT 为 null 。

例子


  
1
2
3
4
5
6
7
8
9


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

返回状态

细节
错误（例如 400 和 404）将返回具相应 HTTP 状态代码，通常会自行解释： 

  
1
2
3
4
5


  
{
    "message": "Error message",
    "status": "Response Status Code",
    "error": " Response Status "
}
状态码 状态 描述

200

OK

400

Bad Request

由于语法无效，服务器无法理解请求。通常是参数错误、重复注册或业务密钥冲突

401

Unauthorized

该请求未被授权。

404

Not Found

未找到注册记录登记。

500

Internal Server Error

服务器遇到了不知道如何处理的情况。

错误代码

常见的错误代码:
状态码 错误信息

解释

400

shipmentWebhookCriteria:must not be blank

shippingWebhookCriteria: 不能为空

400

Webhook already exists.

Webhook 已经存在。

400

The callback URL is not valid.

接收地址无效。

400

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

无法连接 接收端点：+webhook.getCallbackURL() 的发布请求出错

400

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

无法连接 接收端点：无法获得 2xx 成功或 400 错误请求的响应。

400

Inconsistent with the registered secret.

与注册的秘密不一致。

400

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

JSON解析错误：无法识别的字段\“xxxxxx\” xxxxx

404

Can not find related subscription with criteria.

找不到符合条件的相关订阅。

404

Registration not found.

未找到注册。

动作状态

当检测到集装箱的动态和航线/船舶变更 。操作类型将被指示为：NEW / UPDATE / DELETE 以表示动态更改, 路线更改侧用 UPDATE。

操作类型 描述

UPDATE

集装箱动态/路线/信息 变更

NEW

新集装箱动态/信息

DELETE

已删除的集装箱 动态

IMPORTANT: 发货注册后，一旦捕获可用信息，系统将向 Webhook 客户端服务器推送一条完整的信息。首次操作类型将显示为“NEW”，往后的更新将标记为“UPDATE”。

Webhook 客户端服务器应仅返回 HTTP 状态代码 200 以指示成功接收。其他返回状态将被视为失败。

客户端服务器验证和确认

当创建 Webhook 后，系统服务器将立即向指定的接收地址触发一个回调（即请求内容[]），客户端服务器应返回 HTTP 代码 200 以确认并验证双方连接是否健康。否则此端点将失败。

  • 在向客户端服务器触发事件之前，如果 webhook 注册包含秘密，系统服务器将使用 sha1 和 sha256 对秘密进行加密。

  • 系统服务器在回调指定的接收地址时 会传递加密后的 secret，如果 client server 验证加密后的 secret，则返回 200 让 API server 知道 Webhook 已经建立。

更新事件时间

只有在启用 Webhook 的情况下发生运输路线/集装箱动态更改时，才会将更改视为待发送事件。如果当时没有任何可用的 Webhook 连接，则无法在更新货运路线/事件时获得通知。

错误和恢复

在Webhook连接失效时, 即使客户端恢复并重新创建 Webhook，系统不会主动丢失的更新推送到客户端。
客户可以使用 追箱易查询接口 来检索所有货物以维护他们的数据，但无法提供丢失的事件历史记录。

安全性

在互联网上公开接收端点可能会容易受到攻击，因此强烈建议采取安全措施。

建议您将我们的服务器 IP 地址列入白名单，同时拒绝所有外部请求，以防止潜在的有害威胁或对您服务器的不当访问。如果您已对我们的 IP 段应用此网络安全策略， 请通过 customerservices@iqax.com 与我们联系。
Webhook 创建需要一个 HTTPS 回调端点，这样做是为了防止整个网络通道中的信息泄漏。

完整性验证

由于客户端暴露在互联网上，恶意调用可能会到达客户端的服务器，附加在 Webhook 回调的 X-DHST-Signature 和 X-DHST-Signature-256 标头中的密钥，可用于确保调用者的身份，有效载荷的完整性并防止重放攻击。

例子:

1 客户端服务器在注册的 URI 处收到带有标头 X-DHST-Signature-256 的 webhook POST 请求：4F89C033B5EE1A094B6F16B5F315FE7CE180FD1512D9AB031848472E150095C0
2 客户端服务器以前使用密钥（来自 /webhook/shipment APIs 的秘密字段）订阅 webhook：api_token
3 客户端服务器必须验证标头中的 DHST-Signature-256 是否应与加密密钥相同，否则极有可能收到恶意请求。
4 https://en.wikipedia.org/wiki/SHA-2 有关于加密原理的介绍。

支持的运营商

和易孚追箱易支持以下的海运承运人，您还需要在注册货件进行跟踪时提供 carrierScac

您可以查阅我们 支持的运营商名单。如非特别注明，基本上都支持以提单号或订舱号注册货件

如果您发现任何对您的业务很重要但尚未得到支持的运营商，我们可以根据您的使用案例推荐其他不同的选项。请通过 customerservices@iqax.com 与我们联系
Untitled
Ocean Carrier SCAC code BL Registration BKG Registration

ANL Container Line 澳航

ANNU

✓

✓

CK Line 天敬海运

CKLU

✓

✓

CMA-CGM 法国达飞

CMDU

✓

✓

CNC Line 正利

CHNL

✓

✓

COSCO SHIPPING Lines 中远海

COSU

✓

✓

Evergreen 长荣海运

EGLV

✓

✓

Gold Star Line 金星

GOSU

✓

✕

Hamburg Sud 汉堡南美

SUDU

✓

✓

Hapag-Lloyd 赫伯罗特

HLCU

✓

✓

Heung-a 兴亚

11QU

✓

✓

Hyundai 现代

HDMU

✓

✓

Interasia Lines 运达

12AT

✓

✕

KMTC 高丽

KMTC

✓

✓

Maersk 马士基

MAEU

✓

✕

MCC MCC运输

MCCQ

✓

✕

MSC 地中海航运

MSCU

✓

✓

Namsung 南星海运

NSRU

✓

✓

Ocean Network Express 海洋网联

ONEY

✓

✓

OOCL 东方海外

OOLU

✓

✓

PIL 太平

PABV

✓

✓

Sealand 海领

SEAU

✓

✕

Shanghai Jinjiang 锦江

11WJ

✓

✕

Sinokor 长锦

SKLU

✓

✕

Sinotrans 中外运

12IH

✓ (Container# is required)

✕

SITC 海丰

12PD

✓

✕

Swire Shipping 太古船务

CHVW

✓

✓

TS Line 德祥

13DF

✓

✕

Wan Hai 万海

WHLC

✓

✓

Yang Ming Line 阳明

YMJA

✓

✓

Zim Lines 以星

ZIMU

✓

✓

集装箱动态

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 还空

默认情况下，和易孚追箱易将提供"整合版" ， 同时提供选项来过滤特定版本以满足您的需要。

版本 定义 版本参数 推荐使用场景

整合版

结合承运人的路线和使用机器学习模型分析的ETA（包括预测 ETA）以及从 AIS 检测到的 ATA

UNI

需要最新的跟踪数据

标准版

只结合承运人的动态及船期

STD

仅需要承运人提供的数据

进阶版

结合跨承运人船舶时间表以及机器学习的建议

ADV

需要 ML 模型建议的路线和预计到达时间

默认

返回整合版

留空

选择 标准版 和 进阶版 的案例：

考虑以下场景：

1 承运人的网站上正显示该集装箱从 Rotterdam 通过 CMA CGM VASCO DE GAMA 直航运送到 Al' Aqabah
2 数字孪生考虑跨运营商的船期和实况船舶位置，它检测到 CMA CGM VASCO DE GAMA 将跳过Al' Aqabah。这表明该集装箱将前往 Jeddah 中转，并将转乘 COSCO SHIPPING KILIMANJARO 到目的地
标准版 进阶版

1000

1000

只包含承运人当前及最新的的运输路线、集装箱里程碑和时间表

包含

1 丰富的运输路线和船舶推荐（例如在本例中增加 Jeddah 中转 和 推荐中远的 SHIPPING KILIMANJARO ）
2 或 结合及关联 跨运营商的船舶时间表的船舶时间表
3 或 预测 ETA/ETD