轨迹回调说明

基础说明

• 该文档说明的是 TMS 向订阅时传入的 callbackUrl 发起的异步通知
• 请求方法：POST
• Content-Type：application/json
• 当前未附加签名字段，接收方需允许直接接收来自 TMS 的 HTTP 请求

触发时机

当订阅任务出现以下任一变化时，TMS 会发起回调：

1. 标准状态发生变化
2. 新增轨迹事件

如果本次查询既没有状态变化，也没有新增轨迹事件，则不会推送回调。

回调请求体

顶层字段

字段	类型	说明
taskId	uint	订阅任务 ID
carrierCode	string	承运商代码
trackingNumber	string	运单号
externalReferenceNo	string	外部业务单号
standardStatus	string	当前标准状态
carrierStatus	string	当前承运商原始状态
statusChanged	bool	本次回调是否包含状态变化
allEvents	array	当前任务的全部轨迹事件
newEvents	array	本次新增的轨迹事件
pushedAt	datetime	本次回调负载生成时间

事件字段

allEvents[] 与 newEvents[] 的元素结构一致：

字段	类型	说明
taskId	uint	订阅任务 ID
eventTime	datetime	事件时间
eventCode	string	事件代码
status	string	承运商状态值
statusInfo	string	状态补充信息
description	string	事件描述
exceptionDescription	string	异常描述
country	string	国家
state	string	州/省
city	string	城市
postalCode	string	邮编
address	string	地址

回调示例

{
  "taskId": 1001,
  "carrierCode": "FEDEX",
  "trackingNumber": "123456789012",
  "externalReferenceNo": "ORDER-001",
  "standardStatus": "in_transit",
  "carrierStatus": "In Transit",
  "statusChanged": true,
  "allEvents": [
    {
      "taskId": 1001,
      "eventTime": "2024-01-15T10:30:00Z",
      "eventCode": "PU",
      "status": "In Transit",
      "statusInfo": "Picked Up",
      "description": "Shipment picked up",
      "exceptionDescription": "",
      "country": "US",
      "state": "CA",
      "city": "Los Angeles",
      "postalCode": "90001",
      "address": "123 Main St"
    }
  ],
  "newEvents": [
    {
      "taskId": 1001,
      "eventTime": "2024-01-15T10:30:00Z",
      "eventCode": "PU",
      "status": "In Transit",
      "statusInfo": "Picked Up",
      "description": "Shipment picked up",
      "exceptionDescription": "",
      "country": "US",
      "state": "CA",
      "city": "Los Angeles",
      "postalCode": "90001",
      "address": "123 Main St"
    }
  ],
  "pushedAt": "2024-01-15T10:35:00Z"
}

接收方响应要求

• 接收成功后请尽快返回 HTTP 2xx
• TMS 以 HTTP 状态码判断是否成功，不解析业务响应内容
• 非 2xx 响应或请求异常时，TMS 会自动重试

注意事项

• 回调属于异步通知，订阅成功不代表会立刻收到回调
• 回调可能重复投递，接收方应做好幂等处理
• allEvents 表示当前完整轨迹，newEvents 只表示本次新增部分
• pushedAt 是本次回调负载生成时间
• 查询订阅详情接口中的 latestWebhook 可用于查看最近一次回调投递状态