适用场景
快递物流查询接口广泛应用于电商订单追踪、物流管理后台、仓储发货系统及个人快递查询工具。当开发者需要根据快递单号获取实物流转轨迹、判断包裹状态（已揽收/在途/签收/问题件）时，该接口提供标准化的数据接入。典型场景包括：
- 电商平台订单详情页展示物流进度
- 企业内部ERP系统自动同步物流状态
- 第三方物流追踪小程序（需注意调用频率限制）
- 用户投诉处理时快速定位包裹当前位置
接口能力边界
支持的快递公司
本接口覆盖国内100+主流快递公司，包括顺丰(sf)、圆通(yto)、中通(zto)、申通(sto)、韵达(yunda)、极兔(jt)、京东(jd)、EMS(ems)等。上游服务（ALAPI物流源）会自动识别单号归属，同时也支持手动指定公司编码。
两种查询模式
- 自动识别模式：不传
com参数，由系统根据单号规则自动判断快递公司。适合对单号格式有规律认知的场景（如YT开头为圆通）。 - 手动指定模式：传入
com参数明确指定公司编码，可提高识别准确率，尤其当单号格式较模糊时。
隐私保护要求
顺丰和中通的物流轨迹需要核对收件人手机号后4位才能完整返回，否则可能返回脱敏结果或错误。接口通过phone参数传递手机号后4位（非必填，但这两个公司必填）。
数据缓存与频率限制
接口已内置5分钟缓存，相同单号在5分钟内重复查询不会消耗额外QPS。建议前端轮询频率不超过每分钟1次，以避免触发限流。接口QPS为5次/秒，适用于中低并发场景。
请求参数详解
基本参数
| 参数名 | 类型 | 是否必须 | 说明 | 示例值 |
|---|---|---|---|---|
number | string | 是 | 快递单号，8-40位字母或数字组合 | YT7460266600081 |
com | string | 否 | 快递公司编码；不传则自动识别 | yto |
phone | string | 否 | 手机号后4位，仅顺丰/中通实名查询时必填 | 1234 |
鉴权参数（Header）
| 参数名 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
Authorization | string | 否 | API Key，格式为Bearer sk_live_xxx；匿名调用时有每日额度限制，建议正式使用时携带 |
注意：匿名调用存在调用次数上限（以文档实际说明为准），超过后将返回鉴权错误。推荐在生产环境中始终携带API Key。
参数取值细节
- number：支持字母和数字的组合，长度8-40位。对于纯数字单号（如顺丰12位），正常使用。
- com：完整公司编码列表请查阅快递公司编码表（文档中提供）。
- phone：仅当
number为顺丰或中通单号时建议填写；填写错误可能导致轨迹不可见。 - Authorization：API Key可在用户后台获取，格式为
sk_live_开头。若未携带，接口仍可工作但受每日匿名限额约束。
curl 接入示例
以下请求同时使用了com参数手动指定圆通快递，并省略phone（圆通无需手机号）。请务必替换$APIZERO_API_KEY为你的实际密钥。
curl -sS -X GET \ -H "Authorization: Bearer $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/express?number=YT7460266600081&com=yto"若使用自动识别模式，只需不传com：
curl -sS -X GET \ -H "Authorization: Bearer $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/express?number=YT7460266600081"对于顺丰单号（需传phone）：
curl -sS -X GET \ -H "Authorization: Bearer $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/express?number=SF1234567890&com=sf&phone=6789"响应格式（成功状态）
接口返回JSON数组，其中第一个元素为响应内容。成功场景HTTP状态码为200，content_type为application/json。
[ { "content_type": "application/json", "description": "成功", "example": { "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" }, "status": "200" } ]返回值字段解读
外层数组第一个元素即为有效响应体，其example字段包含核心数据。以下为example内部的字段说明：
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 业务状态码：0成功，非0表示查询异常 |
msg | string | 对应code的描述信息 |
request_id | string | 本次请求的唯一标识，可用于日志追踪和问题排查 |
data | object | 查询到的物流数据主体 |
data 对象字段
| 字段 | 类型 | 说明 |
|---|---|---|
com | string | 检测到的快递公司编码 |
com_name | string | 快递公司中文名称 |
number | string | 查询的单号 |
state | int | 包裹状态码：0=未查到, 1=已揽收, 2=在途, 3=签收, 4=问题件 |
status | string | 状态英文标识，如DELIVERED |
status_desc | string | 状态中文描述，如“已签收” |
trace_count | int | 物流轨迹的条目数量 |
traces | array | 物流轨迹数组，按时间倒序排列 |
traces 元素字段
| 字段 | 类型 | 说明 |
|---|---|---|
time | string | 轨迹时间，格式YYYY-MM-DD HH:mm:ss |
content | string | 轨迹文字描述，包含地点和操作详情 |
注意：当state为0时，traces可能为空数组。
常见错误与排错指南
1. 单号格式错误
- 现象：返回
code非0，msg类似“单号格式错误”。 - 排查：检查
number参数是否包含特殊字符、长度是否在8-40位范围内。建议URL编码后传递。
2. 隐私保护参数缺失
- 现象：对于顺丰或中通单号，不传
phone参数时返回轨迹残缺或报错。 - 排查：确认单号所属公司，并补充
phone=xxxx（手机号后4位）。
3. API Key 鉴权失败
- 现象：返回HTTP 401或
code为鉴权类错误。 - 排查：检查
Authorization头的格式是否为Bearer sk_live_...，注意中间有空格。确认API Key未过期且未被撤销。
4. 调用频率超限
- 现象：返回HTTP 429或类似
Too Many Requests。 - 排查：检查QPS是否超过5次/秒。建议在客户端实现指数退避重试，并利用接口的5分钟缓存减少重复查询。
5. 自动识别不准确
- 现象：返回的
com与预期不符，或state一直为0。 - 排查：手动传入
com参数指定快递公司编码，对比结果。部分特殊单号可能无法自动识别。
工程化注意事项
轮询策略设计
由于快递物流状态会随时间变化，前端通常需要定期刷新轨迹。建议：
- 初始查询后，若
state为0或1（未查到/已揽收），可设置较长间隔（10分钟）轮询。 - 若
state为2（在途），建议每5分钟查询一次（利用接口缓存，实际可能每5分钟只发起一次真实请求）。 - 当
state为3（签收）时停止轮询。 - 绝对避免每秒轮询，否则将触发限流并浪费配额。
缓存利用
接口对同一单号有5分钟缓存。可在业务侧额外增加本地缓存：
- 前端在短时间内多次触发（如用户疯狂点击刷新）时，优先返回上一次的结果，直到超过一定时间再发请求。
- 后端也可使用Redis或内存缓存，TTL建议300秒，与接口缓存对齐。
错误重试
对于网络超时或HTTP 5xx错误，建议采用指数退避重试：第一次等待1秒，第二次2秒，第三次4秒，最多重试3次。注意避免在重试期间连续发送多个请求。
并发控制
如果系统需要同时查询大量单号（例如批量导出物流状态），应设计成队列形式，控制并发数不超过5个/秒。可以使用令牌桶或漏桶算法限流。
隐私合规
对于顺丰/中通单号，建议在前端提示用户输入手机号后4位，并明文传递。后端应记录时间戳避免滥用。手机号后4位无需加密传输（HTTPS已提供保护），但不应在日志中明文存储。
日志与监控
每次API调用应记录request_id、number、com、state、响应耗时和错误码。当错误率升高或request_id连续为空时，及时告警。
参考文档
- 快递物流查询接口文档
- 原始接口说明
- 快递公司编码表：请参考上述文档中的附录
