适用场景

物流追踪是电商、供应链和 OA 系统中的高频场景。当用户需要实时查看包裹路由、派送进度或签收状态时，后端通常需要调用第三方物流查询服务。本接口支持 100+ 快递公司自动识别，返回结构化的轨迹列表，可直接用于前端渲染时间线。

典型使用场景包括：

• 电商订单详情页展示物流动态
• 企业内部工单系统的物流跟踪
• 线下门店到货提醒与异常监控

接口能力边界

在动手编码之前，先明确本接口的几个关键能力：

• 公司覆盖：顺丰、圆通、中通、申通、韵达、极兔、京东、EMS 等主流快递，自动识别时无需人为指定公司编码。
• 隐私保护：顺丰、中通单号必须传入 phone 参数（手机号后 4 位）才能返回完整轨迹，其他公司可忽略。
• 缓存机制：接口内建 5 分钟缓存，相同单号在 5 分钟内重复请求不会导致上游重复查询，减少调用配额消耗。
• 响应时效：非实时轮询，建议前端轮询频率不超过每分钟 1 次，避免触发限流。

QPS 限制：5 次/秒，超出会返回 429 状态码。普通业务场景通常够用，若需更高并发需自行申请更高配额（以官方文档为准）。

请求参数与鉴权

Query 参数

参数名	必填	类型	说明	示例值
number	是	string	快递单号，8-40 位字母或数字	YT7460266600081
com	否	string	快递公司编码（如 yto=圆通），缺省由上游自动识别	yto
phone	否	string	手机号后 4 位，仅顺丰/中通必填	1234

认证方式

本接口支持两种鉴权方式：

1. 匿名调用（不传认证头）：每日 30 次调用次数限制，适合开发测试。
2. API Key 鉴权：在请求头中加入 Authorization: Bearer sk_live_xxxxxxxxxxxxxx 或 X-API-Key: sk_live_xxxxxxxxxxxxxx（具体以官方文档为准）。

注意：素材中 curl 示例使用 X-API-Key，但官方文档可能推荐 Authorization。建议在生产环境中两种都测试确认，统一使用官方最新推荐的头部名称。

curl 接入示例

1. 自动识别模式（仅传单号）

curl -sS \
  -X GET \
  -H "X-API-Key: $APIZERO_API_KEY" \
  "https://v1.apizero.cn/api/express?number=YT7460266600081"

2. 手动指定公司编码（减少上游识别耗时）

curl -sS \
  -X GET \
  -H "X-API-Key: $APIZERO_API_KEY" \
  "https://v1.apizero.cn/api/express?number=YT7460266600081&com=yto"

3. 顺丰/中通隐私号段（传入手机尾号）

curl -sS \
  -X GET \
  -H "X-API-Key: $APIZERO_API_KEY" \
  "https://v1.apizero.cn/api/express?number=SF1234567890&phone=4321"

生产环境中请将 $APIZERO_API_KEY 替换为实际的密钥，或使用密钥管理服务注入环境变量。

返回字段解读

成功响应的 JSON 结构如下（仅展示关键字段）：

{
  "code": 0,
  "data": {
    "com": "yto",
    "com_name": "圆通快递",
    "number": "YT7460266600081",
    "state": 3,
    "status": "DELIVERED",
    "status_desc": "已签收",
    "trace_count": 3,
    "traces": [
      {
        "content": "【上海市】您的快件已签收，签收人：本人",
        "time": "2026-05-06 14:23:11"
      },
      {
        "content": "【上海市】快件正在派送途中（派件员：张三 138****1234）",
        "time": "2026-05-06 09:15:32"
      },
      {
        "content": "【广州市】快件离开 广州转运中心 发往 上海转运中心",
        "time": "2026-05-05 22:41:08"
      }
    ]
  },
  "msg": "成功",
  "request_id": "abc123def456"
}

字段说明

字段	类型	说明
code	int	业务状态码：0 成功，非 0 失败
data.com	string	快递公司编码（如 yto）
data.com_name	string	快递公司中文名
data.number	string	快递单号
data.state	int	快递状态码：0=未查到, 1=已揽收, 2=在途, 3=签收, 4=问题件
data.status	string	英文状态（DELIVERED 等）
data.status_desc	string	中文状态描述
data.trace_count	int	轨迹条数
data.traces	array	轨迹列表，按时间倒序排列，每个对象包含 time 和 content
msg	string	状态描述
request_id	string	请求唯一标识，可用于排查问题

状态码速查

• 0：未查到（单号无效或刚揽收尚未同步）
• 1：已揽收
• 2：在途（运输中）
• 3：已签收
• 4：问题件（异常如退件、拒收、滞留等）

常见错误排查

1. HTTP 状态码层面

状态码	原因	处理建议
400	参数错误，如单号为空或格式不符	检查 number 参数长度（8-40 位）
401	鉴权失败	确认 API Key 有效且头部名称正确
429	请求频率超过 5 QPS 或每日匿名额度用尽	降低轮询频率，或添加认证头
5xx	服务端异常	等待后重试，并向官方反馈

2. 业务状态码非 0

例如返回 {"code": 1, "msg": "快递单号无效"} 时，常见原因：

• 单号输入错误（多一位少一位）
• 单号所属快递公司不在支持列表内（虽称 100+，但个别小众快递可能不覆盖）
• 单号刚生成，物流信息尚未同步到上游，可以间隔 5-10 分钟后重查

3. 顺丰/中通返回空轨迹

检查 phone 参数是否传入手机号后 4 位。若用户未提供，可提示用户输入，或默认尝试无 phone 查询（但可能只能获得到基础状态）。

工程化注意事项

1. 轮询策略

• 轮询间隔：建议至少 30 秒一次，接口内建 5 分钟缓存，所以即使 30 秒轮询一次，实际也只会在第一个 5 分钟内触发一次上游查询，后续都直接返回缓存数据，不会产生额外计费。
• 终止条件：当 state 为 3（已签收）或 4（问题件）时停止轮询，前端提示最终状态。
• 错误降级：若连续 3 次返回 429 或 5xx，可以进入指数退避（如 1 分钟、2 分钟、4 分钟）并记录日志。

2. 缓存设计

即使接口有 5 分钟缓存，但如果你在多线程/分布式环境下反复查询相同单号，建议在应用层也加入一级内存缓存（例如 1 分钟过期），减少网络开销。示例伪代码（Java）：

Cache<String, ExpressResponse> cache = Caffeine.newBuilder()
    .expireAfterWrite(1, TimeUnit.MINUTES)
    .maximumSize(1000)
    .build();

3. 隐私处理

用户手机号后 4 位属于敏感信息，建议：

• 在客户端仅展示最后 4 位，完整手机号不应暴露在前端。
• 后端存储时需对 phone 参数进行脱敏（如只记录掩码后的字符串）。
• API 调用时避免将 phone 明文记录到日志中，可做 maskPhone() 处理。

4. 多公司编码映射

虽然接口支持自动识别，但在实际业务中建议维护一份本地公司编码表，将用户选择的前端快递公司名称与 com 参数映射，避免每次调用都让上游做一次不明智的识别。常见编码示例：

中文名	编码
顺丰	sf
圆通	yto
中通	zto
申通	sto
韵达	yunda
极兔	jt
京东	jd
EMS	ems

5. 异常监控与告警

在生产环境，建议针对以下指标设置监控：

• 接口调用成功率（200 且 code=0 的比例，低于 95% 触发告警）
• 平均响应时间（超过 2 秒可能说明上游异常或网络抖动）
• 429 频率（超过 10 次/小时提示可能需要扩容或调整轮询策略）

参考文档

• 官方文档页：https://apizero.cn/aidocs/express
• 原始 markdown 文档：https://apizero.cn/aidocs/express/raw.md

本文示例中的 API 地址、参数和响应结构均基于上述文档撰写，如有变更请以官方最新文档为准。