适用场景快递物流查询接口在电商物流追踪、订单履约系统、客服工单平台、个人快递管理等场景中广泛使用。当需要根据运单号获取实时轨迹时调用一个可靠的API可以大幅减少自建爬虫的维护维护复杂度。本教程围绕一个具体接口展开追求“最小可运行”原则——从零开始仅用一条curl命令就能拿到数据再逐步扩展到带参数的调用和代码集成。接口能力边界数据源基于 ALAPI 物流源覆盖国内全部主流快递支持 100 快递公司。单号识别支持“自动识别”不传com参数和“手动指定公司编码”两种模式。自动识别适用于大部分常见单号但若识别错误如顺丰单号误识别为其他公司可手动传入正确的com纠正。隐私保护顺丰、中通因隐私保护要求必须传手机号后 4 位参数phone否则无法查询轨迹。返回数据包含单号、快递公司编码与中文名、状态码0未查到, 1已揽收, 2在途, 3签收, 4问题件、状态描述、完整物流轨迹按时间倒序每条含时间和文字描述。QPS 限制5 次/秒建议前端轮询频率不超过每分钟 1 次。接口已内建 5 分钟缓存短时间重复查询相同单号会命中缓存不消耗配额。请求参数与鉴权Query 参数参数名必填类型说明示例值number是string快递单号8-40 位字母或数字YT7460266600081com否string快递公司编码例如yto、sf、zto。缺省时由上游自动识别ytophone否string手机号后 4 位数字顺丰/中通必填其他快递可忽略1234Header 参数参数名必填类型说明示例值Authorization否stringAPI Key 鉴权头格式Bearer sk_live_xxx。匿名调用时可省略每日 30 次Bearer sk_live_xxxxxxxxxxxxxxX-API-Key否string另一种鉴权方式与 Authorization 二选一部分版本使用此头sk_live_xxxxxxxxxxxxxx说明以下示例统一使用X-API-Key方式你也可以使用Authorization: Bearer key替换。匿名调用时两个头都不传即可但每天有次数限制。最小可运行示例curl匿名请求无需 API Key每日 30 次curl -sS \ -X GET \ https://v1.apizero.cn/api/express?numberYT7460266600081如果单号是顺丰或中通必须追加phone1234curl -sS \ -X GET \ https://v1.apizero.cn/api/express?numberSF1234567890phone9999带 API Key 的请求推荐生产环境使用curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/express?numberYT7460266600081将环境变量APIZERO_API_KEY替换为你的真实密钥即可。如果不想用环境变量直接内联字符串注意安全curl -sS -H X-API-Key: sk_live_xxxxxxxxxxxxxx https://v1.apizero.cn/api/express?numberYT7460266600081使用 Python 请求若需要在脚本中集成可以用requests库。以下示例实现了异步缓存友好单次查询不轮询import requests import json # 配置 API Key匿名时设为 None 或空字符串 API_KEY sk_live_xxxxxxxxxxxxxx # 替换为你自己的 key BASE_URL https://v1.apizero.cn/api/express def query_express(number, comNone, phoneNone): headers {} if API_KEY: headers[X-API-Key] API_KEY params {number: number} if com: params[com] com if phone: params[phone] phone resp requests.get(BASE_URL, paramsparams, headersheaders) resp.raise_for_status() # 非 2xx 抛出异常 return resp.json() # 示例自动识别单号 result query_express(YT7460266600081) print(json.dumps(result, indent2, ensure_asciiFalse))若查询顺丰单号result query_express(SF1234567890, phone9998)返回字段解读成功响应的 JSON 结构如下以YT7460266600081为例{ 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 成功其他为错误见错误处理msgstring对应状态码的中文描述request_idstring单次请求的唯一标识可用于排查日志data.comstring快递公司编码例如yto、sfdata.com_namestring快递公司中文名如“圆通快递”data.numberstring查询的快递单号data.stateint物流状态码0未查到, 1已揽收, 2在途, 3签收, 4问题件data.statusstring英文状态如DELIVERED、IN_TRANSITdata.status_descstring中文状态描述如“已签收”“在途中”data.trace_countint轨迹节点数量data.tracesarray轨迹列表按时间倒序每个元素包含content和timetraces[].timestring轨迹发生时间格式YYYY-MM-DD HH:mm:sstraces[].contentstring轨迹文本描述可能包含脱敏的个人信息如手机号中间四位****常见错误处理业务错误码HTTP 200 但 code ≠ 0错误码含义常见原因及处理1001缺少必要参数未传number或格式不符合 8-40 位1002无效的单号单号不存在或快递公司无法识别可尝试手动指定com1003隐私保护验证失败顺丰/中通未传或传错phone检查手机号后4位是否正确1004请求过于频繁超过 QPS 限制建议降低轮询频率或使用缓存HTTP 状态码异常401 UnauthorizedAPI Key 错误或过期检查Authorization或X-API-Key头的值。429 Too Many Requests超过 QPS 配额等待几秒后重试。500/503服务端异常可隔几秒重试一次建议指数退避。响应示例错误时{ code: 1003, msg: 隐私保护验证失败请提供手机号后4位, request_id: err789xyz }工程化注意事项API Key 安全不要将密钥硬编码在客户端代码或公开仓库中。推荐使用环境变量或密钥管理服务如 Vault。缓存策略由于接口内建 5 分钟缓存前端轮询建议间隔 60 秒以上。对于已签收的单号可以停止轮询。隐私字段处理traces中的content已脱敏手机号中间四位****前端展示时无需额外脱敏。自动识别 vs 手动指定自动识别方便但不一定准遇到识别错误时可手动传入com。常见公司编码对照sf顺丰,yto圆通,zto中通,sto申通,yunda韵达,jt极兔,jd京东,emsEMS。异常重试网络和服务端错误5xx可重试 3 次间隔 2 秒。业务错误码如无效单号不应重试。QPS 监控生产环境建议在网关层做限流避免单个用户高频请求影响整体。参考文档接口原始文档https://apizero.cn/aidocs/express/raw.md交互式文档页https://apizero.cn/aidocs/express公司编码列表可在文档页中查询各快递公司的com参数值
