适用场景物流追踪是电商、供应链和 OA 系统中的高频场景。当用户需要实时查看包裹路由、派送进度或签收状态时后端通常需要调用第三方物流查询服务。本接口支持 100 快递公司自动识别返回结构化的轨迹列表可直接用于前端渲染时间线。典型使用场景包括电商订单详情页展示物流动态企业内部工单系统的物流跟踪线下门店到货提醒与异常监控接口能力边界在动手编码之前先明确本接口的几个关键能力公司覆盖顺丰、圆通、中通、申通、韵达、极兔、京东、EMS 等主流快递自动识别时无需人为指定公司编码。隐私保护顺丰、中通单号必须传入phone参数手机号后 4 位才能返回完整轨迹其他公司可忽略。缓存机制接口内建 5 分钟缓存相同单号在 5 分钟内重复请求不会导致上游重复查询减少调用配额消耗。响应时效非实时轮询建议前端轮询频率不超过每分钟 1 次避免触发限流。QPS 限制5 次/秒超出会返回 429 状态码。普通业务场景通常够用若需更高并发需自行申请更高配额以官方文档为准。请求参数与鉴权Query 参数参数名必填类型说明示例值number是string快递单号8-40 位字母或数字YT7460266600081com否string快递公司编码如 yto圆通缺省由上游自动识别ytophone否string手机号后 4 位仅顺丰/中通必填1234认证方式本接口支持两种鉴权方式匿名调用不传认证头每日 30 次调用次数限制适合开发测试。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?numberYT74602666000812. 手动指定公司编码减少上游识别耗时curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/express?numberYT7460266600081comyto3. 顺丰/中通隐私号段传入手机尾号curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/express?numberSF1234567890phone4321生产环境中请将$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 }字段说明字段类型说明codeint业务状态码0 成功非 0 失败data.comstring快递公司编码如 ytodata.com_namestring快递公司中文名data.numberstring快递单号data.stateint快递状态码0未查到, 1已揽收, 2在途, 3签收, 4问题件data.statusstring英文状态DELIVERED 等data.status_descstring中文状态描述data.trace_countint轨迹条数data.tracesarray轨迹列表按时间倒序排列每个对象包含time和contentmsgstring状态描述request_idstring请求唯一标识可用于排查问题状态码速查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 分钟过期减少网络开销。示例伪代码JavaCacheString, 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京东jdEMSems5. 异常监控与告警在生产环境建议针对以下指标设置监控接口调用成功率200 且 code0 的比例低于 95% 触发告警平均响应时间超过 2 秒可能说明上游异常或网络抖动429 频率超过 10 次/小时提示可能需要扩容或调整轮询策略参考文档官方文档页https://apizero.cn/aidocs/express原始 markdown 文档https://apizero.cn/aidocs/express/raw.md本文示例中的 API 地址、参数和响应结构均基于上述文档撰写如有变更请以官方最新文档为准。