国际出库物流追踪 API

按任一支持的单号查询

公开物流查询场景通常不知道 HioBuy 发货单 ID，此时使用：

GET /v1/fulfillment/tracking?sn=9400111899223857654321
Authorization: Bearer <API_KEY>

必填参数 sn 可以是物流单号（logistics_sn）、仓库订单号 （order_sn）或开发者提供的外部单号（client_order_sn）。HioBuy 会原样转发该值，由仓库自动判断类型；构造查询字符串时请对 sn 进行 URL 编码。接口需要 tracking:read 权限。

API Key 必须保存在服务端。公开物流查询页面应先请求开发者自己的后端， 再由后端请求 HioBuy API；不要把 API Key 写入浏览器代码。

已知 HioBuy 发货单 ID 或 external_shipment_id 时，仍可使用下面原有的 按 ID 查询接口。

GET /v1/fulfillment/shipments/{shipment_id}/tracking — 履约仓 → 海外收件人。

不是 国内代购物流（卖家 → 仓库）。
不是 包裹轨迹（HioBuy 仓内入库时间线）。
不是 发货单详情：详情给的是运单号（international_tracking、shipping_legs[]、boxes[].tracking）以及仓库业务 timeline[]（创建 / 打包 / 支付）。本接口返回承运商扫描节点，字段形态与详情子集一致。

路径 {shipment_id} 可以是 HioBuy 运输单系统 id，也可以是创单时提交的 external_shipment_id。纯数字值作为 shipment_id 传给仓库；包含任意非数字字符的值作为 external_shipment_id 传给仓库。纯数字保留给内部 ID，建议开发者编号添加前缀，例如 shp_MY-INTL-ORDER-001。可选 language 用于沙箱展示文案。

仓库上游：POST /api/gateway-worker/v1/shipments/track。已作废：POST /v1/fulfillment/shipments/logistics/trace。

请求

GET /v1/fulfillment/shipments/107/tracking?language=en
Authorization: Bearer <API_KEY>

响应

与详情对齐的子集：id、order_sn、shipping_channel、international_tracking、status、status_label、interception、timeline[]。

interception 独立于发货单生命周期 status。未申请拦截时为 null； 申请后返回当前拦截请求状态，但不会替代发货单本身的状态。

每个 timeline[] 节点必须包含 code、status、title、occurred_at、 details。程序逻辑使用稳定的 code 和 status，不要解析本地化的 title； 时间必须是带时区的 ISO 8601，无附加上下文时 details 返回 {}，事件按 时间倒序返回，code 不能是空字符串或 null。

{
  "id": "118",
  "order_sn": "JIYUNRI1358",
  "shipping_channel": {
    "code": "CJ-SEA",
    "name": "E-commerce Sea - CJ"
  },
  "international_tracking": {
    "tracking_number": null,
    "carrier": null
  },
  "status": "PENDING",
  "status_label": "待处理",
  "interception": null,
  "timeline": [
    {
      "code": "SHIPMENT_CREATED",
      "status": "PENDING",
      "title": "订单已创建",
      "occurred_at": "2026-08-23T11:14:58+08:00",
      "details": {}
    }
  ],
  "request_id": "req_xxx"
}

字段说明见 履约响应模型。 标准事件码和拦截语义见 发货单 · Timeline 契约。