查询物流轨迹

按 po_number 实时查询 Huixing Express 物流轨迹节点，包含最新状态与终态判定。

预报单发货后，平台通过 Huixing Express 承运。通过本接口可按 po_number 实时查询包裹的完整物流轨迹节点（最新在前），以及是否已签收/派送失败/退回等终态信息。平台同时提供 tracking.changed Webhook 轨迹变化推送，二者可配合使用：收到推送后调用本接口获取完整轨迹。

接口说明

项	值
方法	`GET`
路径	`/open/v1/forecasts/tracking`
鉴权	ApiKey 鉴权

请求

请求头

请求头	必填	说明
`X-Api-Key`	是	ApiKey，详见鉴权说明

查询参数

参数	类型	必填	说明
`po_number`	string	是	PO 号（业务键，提交预报单时传入）

请求示例

curl 'https://open.test.huixingguoji.com/open/v1/forecasts/tracking?po_number=180401699' \
  -H 'X-Api-Key: YOUR_API_KEY'

响应

成功（HTTP 200）

{
  "code": "0",
  "message": "success",
  "data": {
    "po_number": "180401699",
    "is_shipped": true,
    "is_terminal": false,
    "latest_status": "In Delivery",
    "nodes": [
      {
        "order_no": "180401699",
        "address": "Johannesburg, GP",
        "content": "Parcel arrived at local delivery station",
        "status": "In Transit",
        "create_time": "2026-08-14 09:23:11",
        "times": "(GMT+08:00)",
        "admin_status": "In Delivery"
      },
      {
        "order_no": "180401699",
        "address": "Durban",
        "content": "Parcel departed from origin hub",
        "status": "In Transit",
        "create_time": "2026-08-12 21:05:47",
        "times": "(GMT+08:00)",
        "admin_status": "In Transit"
      }
    ]
  }
}

字段说明

字段	类型	说明
`po_number`	string	PO 号
`is_shipped`	boolean	预报单是否已发货（未发货时轨迹通常为空）
`is_terminal`	boolean	是否已达终态（签收 / 派送失败 / 退回发货地）
`latest_status`	string	最新节点的管理状态；无轨迹时为空字符串
`nodes`	array	轨迹节点，最新在前；刚发货尚无轨迹时为空数组

nodes[] 节点字段：

字段	类型	说明
`order_no`	string	订单号
`address`	string	节点地址
`content`	string	轨迹内容描述
`status`	string	节点状态
`create_time`	string	轨迹时间（`yyyy-MM-dd HH:mm:ss`）
`times`	string	时间格式（如 `(GMT+08:00)`）
`admin_status`	string	管理状态（变化判定与终态识别依据）

终态 admin_status 取值：Delivery Success（签收）、Delivery Failure（派送失败）、Parcel Return to Origin（退回发货地）。

失败

常见错误码（完整列表见错误码）：

错误码	含义	触发场景
`42201`	字段校验失败	未携带 `po_number`
`40401`	包裹不存在	`po_number` 不存在或不属于当前租户
`50001`	系统异常	承运商轨迹接口暂时不可用，请稍后重试

查询物流轨迹

On this page