<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 快递物流查询

> 快递物流查询，支持顺丰、圆通、中通、申通、韵达、极兔、京东、EMS 等 100+ 主流快递公司，自动识别单号所属公司，返回完整物流轨迹。

基于 ALAPI 物流源，覆盖国内全部主流快递。支持「自动识别」（不传 com 参数即可）和「手动指定公司编码」两种模式。顺丰、中通因隐私保护需求，必须传手机号后 4 位（参数 phone）。

返回字段包含：单号、快递公司编码、公司中文名、状态码（0=未查到, 1=已揽收, 2=在途, 3=签收, 4=问题件）、状态描述、完整物流轨迹（按时间倒序，包含每条轨迹的时间和文字描述）。

建议前端轮询频率不超过每分钟 1 次，本接口已内建 5 分钟缓存以节省调用次数。

## 1. 基本信息

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

## 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)

```bash
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. 响应示例

```json
{
    "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 业务错误透传消息（用户友好）

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/express`

Source: `https://apizero.cn/aidocs/express/raw.md`
Last updated: 2026-05-11T16:16:07+08:00