快递物流查询express

快递物流查询，支持顺丰、圆通、中通、申通、韵达、极兔、京东、EMS 等 100+ 主流快递公司，自动识别单号所属公司，返回完整物流轨迹。基于 ALAPI 物流源，覆盖国内全部主流快递。支持「自动识别」（不传 com 参数即可）和「手动指定公司编码」两种模式。顺丰、中通因隐私保护需求，必须传手机号后 4 位（参数 phone）。返回字段包含：单号、快递公司编码、公司中文名、状态码（0=未查到, 1=已揽收, 2=在途, 3=签收, 4=问题件）、状态描述、完整物流轨迹（按时间倒序，包含每条轨迹的时间和文字描述）。建议前端轮询频率不超过每分钟 1 次，本接口已内建 5 分钟缓存以节省调用次数。

1. 基本信息

接口地址	`https://v1.apizero.cn/api/express`
请求方法	`GET`
分类	life
提供方	极数本源
计费模式	免费试用
单次消耗	0 积分
起步价	—
QPS 限制	5 req/s
每日免费额度	100 次（已认证用户）
匿名每日额度	30 次（无 API Key）
VIP 免费	否
调用次数

2. 认证

匿名每日 30 次、QPS 2；登录用户每日 100 次、QPS 5（全部免费）。顺丰 / 中通必须传 phone 参数（手机号后 4 位），否则上游返回错误。

获取 API Key：登录 https://apizero.cn/account/keys

3. 请求参数

参数名	类型	必填	说明	示例
`number`	`string`	是	快递单号（8-40 位字母或数字）	`YT7460266600081`
`com`	`string`	否	快递公司编码（如 sf=顺丰、yto=圆通、zto=中通、sto=申通、yunda=韵达、jt=极兔、jd=京东、ems=EMS）；缺省由上游自动识别	`yto`
`phone`	`string`	否	手机号后 4 位数字（仅顺丰 / 中通必填，因隐私保护要求）	`1234`

4. 请求头

Header	类型	必填	说明	示例
`Authorization`	`string`	否	API Key 鉴权头，格式 Bearer sk_live_xxx；匿名调用时可省略（每日 30 次免费）	`Bearer sk_live_xxxxxxxxxxxxxx`

5. 请求示例 (cURL)

curl "https://v1.apizero.cn/api/express?number=YT7460266600081&com=yto&phone=1234&key=YOUR_API_KEY"

6. 响应字段

字段	类型	说明	示例
`number`	`string`	快递单号（与请求一致或上游修正后的）	—
`com`	`string`	快递公司编码（如 sf、yto）	—
`com_name`	`string`	快递公司中文名称	—
`state`	`number`	状态码：0=未查到 / 1=已揽收 / 2=在途 / 3=已签收 / 4=问题件 / 其他	—
`status`	`string`	状态英文标识（如 EMPTY、PROCESSING、DELIVERED）	—
`status_desc`	`string`	状态中文描述（人类可读，建议直接显示给用户）	—
`trace_count`	`number`	物流轨迹条数（traces 数组长度）	—
`traces`	`array`	物流轨迹列表（按时间倒序，最新在前）	—
`traces[].time`	`string`	该轨迹的时间（YYYY-MM-DD HH:mm:ss）	—
`traces[].content`	`string`	该轨迹的中文描述（如「已揽收，离开广州转运中心」）	—

7. 响应示例

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

8. 错误码

code	status	说明
`4000`	`—`	参数错误：number 为空 / 格式不正确 / 顺丰中通缺 phone / com 编码不被支持等
`4015`	`—`	匿名调用每日额度用完，需要 API Key
`4029`	`—`	QPS 超限
`4030`	`—`	今日额度用完
`5020`	`—`	上游服务不可用
`5030`	`—`	上游 Key 未配置或异常（管理员问题）

9. 变更日志

1.0.0(2026-05-06)
- 首次上线，支持 100+ 主流快递公司物流查询
- 内建 5 分钟缓存（节省上游 quota）
- 自动识别快递公司，无需手动指定 com
- 支持顺丰 / 中通的隐私保护参数 phone
- 上游 422/400 业务错误透传消息（用户友好）