适用场景

快递物流查询接口在电商物流追踪、订单履约系统、客服工单平台、个人快递管理等场景中广泛使用。当需要根据运单号获取实时轨迹时，调用一个可靠的API可以大幅减少自建爬虫的维护维护复杂度。本教程围绕一个具体接口展开，追求“最小可运行”原则——从零开始，仅用一条curl命令就能拿到数据，再逐步扩展到带参数的调用和代码集成。

接口能力边界

• 数据源：基于 ALAPI 物流源，覆盖国内全部主流快递，支持 100+ 快递公司。
• 单号识别：支持“自动识别”（不传 com 参数）和“手动指定公司编码”两种模式。自动识别适用于大部分常见单号，但若识别错误（如顺丰单号误识别为其他公司），可手动传入正确的 com 纠正。
• 隐私保护：顺丰、中通因隐私保护要求，必须传手机号后 4 位（参数 phone），否则无法查询轨迹。
• 返回数据：包含单号、快递公司编码与中文名、状态码（0=未查到, 1=已揽收, 2=在途, 3=签收, 4=问题件）、状态描述、完整物流轨迹（按时间倒序，每条含时间和文字描述）。
• QPS 限制：5 次/秒，建议前端轮询频率不超过每分钟 1 次。接口已内建 5 分钟缓存，短时间重复查询相同单号会命中缓存，不消耗配额。

请求参数与鉴权

Query 参数

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

Header 参数

参数名	必填	类型	说明	示例值
Authorization	否	string	API Key 鉴权头，格式 Bearer sk_live_xxx。匿名调用时可省略（每日 30 次）	Bearer sk_live_xxxxxxxxxxxxxx
X-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?number=YT7460266600081"

如果单号是顺丰或中通，必须追加 &phone=1234：

curl -sS \
  -X GET \
  "https://v1.apizero.cn/api/express?number=SF1234567890&phone=9999"

带 API Key 的请求（推荐生产环境使用）

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

将环境变量 APIZERO_API_KEY 替换为你的真实密钥即可。如果不想用环境变量，直接内联字符串（注意安全）：

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

使用 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, com=None, phone=None):
    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, params=params, headers=headers)
    resp.raise_for_status()  # 非 2xx 抛出异常
    return resp.json()

# 示例：自动识别单号
result = query_express("YT7460266600081")
print(json.dumps(result, indent=2, ensure_ascii=False))

若查询顺丰单号：

result = query_express("SF1234567890", phone="9998")

返回字段解读

成功响应的 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"
}

字段说明

字段	类型	说明
code	int	业务状态码：0 成功，其他为错误（见错误处理）
msg	string	对应状态码的中文描述
request_id	string	单次请求的唯一标识，可用于排查日志
data.com	string	快递公司编码，例如 yto、sf
data.com_name	string	快递公司中文名，如“圆通快递”
data.number	string	查询的快递单号
data.state	int	物流状态码：0=未查到, 1=已揽收, 2=在途, 3=签收, 4=问题件
data.status	string	英文状态，如 DELIVERED、IN_TRANSIT
data.status_desc	string	中文状态描述，如“已签收”“在途中”
data.trace_count	int	轨迹节点数量
data.traces	array	轨迹列表，按时间倒序，每个元素包含 content 和 time
traces[].time	string	轨迹发生时间，格式 YYYY-MM-DD HH:mm:ss
traces[].content	string	轨迹文本描述，可能包含脱敏的个人信息（如手机号中间四位 ****）

常见错误处理

业务错误码（HTTP 200 但 code ≠ 0）

错误码	含义	常见原因及处理
1001	缺少必要参数	未传 number 或格式不符合 8-40 位
1002	无效的单号	单号不存在或快递公司无法识别，可尝试手动指定 com
1003	隐私保护验证失败	顺丰/中通未传或传错 phone，检查手机号后4位是否正确
1004	请求过于频繁	超过 QPS 限制，建议降低轮询频率或使用缓存

HTTP 状态码异常

• 401 Unauthorized：API Key 错误或过期，检查 Authorization 或 X-API-Key 头的值。
• 429 Too Many Requests：超过 QPS 配额，等待几秒后重试。
• 500/503：服务端异常，可隔几秒重试一次（建议指数退避）。

响应示例（错误时）

{
  "code": 1003,
  "msg": "隐私保护验证失败，请提供手机号后4位",
  "request_id": "err789xyz"
}

工程化注意事项

1. API Key 安全：不要将密钥硬编码在客户端代码或公开仓库中。推荐使用环境变量或密钥管理服务（如 Vault）。
2. 缓存策略：由于接口内建 5 分钟缓存，前端轮询建议间隔 60 秒以上。对于已签收的单号，可以停止轮询。
3. 隐私字段处理：traces 中的 content 已脱敏（手机号中间四位 ****），前端展示时无需额外脱敏。
4. 自动识别 vs 手动指定：自动识别方便但不一定准，遇到识别错误时可手动传入 com。常见公司编码对照：sf=顺丰, yto=圆通, zto=中通, sto=申通, yunda=韵达, jt=极兔, jd=京东, ems=EMS。
5. 异常重试：网络和服务端错误（5xx）可重试 3 次，间隔 2 秒。业务错误码（如无效单号）不应重试。
6. QPS 监控：生产环境建议在网关层做限流，避免单个用户高频请求影响整体。

参考文档

• 接口原始文档：https://apizero.cn/aidocs/express/raw.md
• 交互式文档页：https://apizero.cn/aidocs/express
• 公司编码列表：可在文档页中查询各快递公司的 com 参数值