追踪 API

使用公开追踪接口展示一票货件对客户安全的配送状态。该接口可匿名访问，但只接受货件的 tracking_number；包裹扫描码和内部标识不能替代它。

接口

方法	URL	适用场景
GET	https://mexpress.nz/api/v1/public/tracking/{tracking_number}/	需要读取状态投影。
HEAD	https://mexpress.nz/api/v1/public/tracking/{tracking_number}/	只需要状态码和响应头。

HEAD 与 GET 具有相同的状态码和限流行为，但不返回响应体。

发起请求

GET

curl --fail-with-body \
  'https://mexpress.nz/api/v1/public/tracking/MX123456789/'

HEAD

curl --head \
  'https://mexpress.nz/api/v1/public/tracking/MX123456789/'

读取成功响应

200 OK 返回安全状态、包裹摘要和客户可见时间线。以下数值仅为示例；应以响应字段的含义为准， 不要把示例值当作固定结果。

字段	用途
tracking_number	确认正在展示的货件。
status、status_label	展示当前对客户安全的状态。
milestone、reason	在存在时补充客户可见上下文。
package_count、package_summary	汇总该货件的包裹。
occurred_at、timeline	展示客户可见的状态历史。
projection_revision	供你的缓存或界面识别状态投影是否变化。

{
  "tracking_number": "MX123456789",
  "status": "out_for_delivery",
  "milestone": "out_for_delivery",
  "reason": null,
  "status_label": "Out for delivery",
  "package_count": 1,
  "package_summary": { "out_for_delivery": 1 },
  "projection_revision": 7,
  "occurred_at": "2026-08-02T01:15:00.000000Z",
  "timeline": [
    {
      "status": "out_for_delivery",
      "label": "Out for delivery",
      "occurred_at": "2026-08-02T01:15:00.000000Z"
    }
  ]
}

响应不会包含收件人联系方式或地址、包裹扫描码、POD 媒体、精确位置、司机或设备身份、计费、 原始扫描证据或内部字段。

处理 404 与 429

状态	含义	集成端应如何处理
404	追踪号未知或暂不公开。	展示统一的未找到结果；不要暴露不同原因。
429	匿名请求被限流。	读取正数 Retry-After 响应头，并至少等待该时长。

稳态限额为每个源 IP 5 req/s，突发容量 30；同时还有共享服务限额。处理 429 时，将 Retry-After 与指数退避和随机抖动结合。不要紧密循环重试，也不要把限流当成追踪号存在的信号。 只在客户体验确实需要更新时轮询；同一追踪号每分钟最多一次是安全的默认值。

验证清单

• [ ] GET 只向客户展示文档列出的安全投影字段。
• [ ] 只在不需要响应体时使用 HEAD。
• [ ] 404 在客户界面中只有一个中性处理结果。
• [ ] 429 先遵守正数 Retry-After，再执行退避与抖动。

下一步

如果系统需要配送驱动的更新，请继续阅读 Webhooks。