← 返回 API 目录 🚀 直接访问 /track

物流轨迹查询

GET / POST /track ● 在线 查询类
输入运单号查询实时物流轨迹，不传快递公司时自动识别

🔎 用途说明

输入运单号查询实时物流轨迹，不传快递公司时自动识别

核心接口。输入运单号即可查询完整物流轨迹（快递公司、当前状态、每条轨迹的时间/地点/描述）。不传 carrier 参数时按单号格式自动识别快递公司；也可手动指定。支持 GET query 或 POST JSON body。无商业 API Key 依赖——数据源为快递100 公开查询接口。

🧾 请求参数

参数位置必填类型说明示例值
no query ● 必填 string 运单号（最少 5 位），自动去除空格并转大写 73717993242626
carrier query ○ 可选 string 快递公司编码。不传则自动识别。支持中英文别名（顺丰/sf、中通/zto 等） zhongtong
phone query ○ 可选 string 收件人手机号（顺丰等部分快递公司可增强查询精度） 13800000000

💻 请求示例

# 自动识别（推荐，最简用法）
curl "https://api.1912212.xyz/track?no=73717993242626"

# 指定快递公司
curl "https://api.1912212.xyz/track?no=SF1234567890123&carrier=shunfeng"

# POST JSON（带手机号）
curl -X POST -H "Content-Type: application/json" \
  -d '{"no":"73717993242626","phone":"13800000000"}' \
  "https://api.1912212.xyz/track"
// 自动识别（最简用法）
const resp = await fetch('https://api.1912212.xyz/track?no=73717993242626');
const data = await resp.json();
if (data.ok) {
  console.log(data.data.statusText); // "已签收"
  data.data.events.forEach(e => console.log(e.time, e.description));
} else {
  console.error(data.error.code, data.error.message);
}

// POST JSON（带手机号）
const resp2 = await fetch('https://api.1912212.xyz/track', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ no: '73717993242626', phone: '13800000000' }),
});
const data2 = await resp2.json();
import requests

# 自动识别（最简用法）
resp = requests.get('https://api.1912212.xyz/track', params={'no': '73717993242626'})
data = resp.json()
if data['ok']:
    print(data['data']['statusText'])
    for e in data['data']['events']:
        print(e['time'], e['description'])
else:
    print(data['error']['code'], data['error']['message'])

# POST JSON（带手机号）
resp2 = requests.post(
    'https://api.1912212.xyz/track',
    json={'no': '73717993242626', 'phone': '13800000000'}
)
data2 = resp2.json()

📦 返回示例（真实脱敏）

{
  "ok": true,
  "data": {
    "carrier": "zhongtong",
    "carrierName": "中通快递",
    "number": "73717993242626",
    "status": "delivered",
    "statusText": "已签收",
    "events": [
      {
        "time": "2026-11-02 15:32:10",
        "description": "【北京朝阳区】 快件已由菜鸟驿站代收",
        "location": "北京市朝阳区"
      },
      {
        "time": "2026-11-02 08:15:00",
        "description": "快件到达 北京朝阳分拨中心，准备派送",
        "location": "北京市朝阳区"
      },
      {
        "time": "2026-11-01 22:40:00",
        "description": "快件从 上海转运中心 发出",
        "location": "上海市"
      }
    ],
    "queriedAt": 1762118400,
    "source": "kuaidi100"
  }
}

📝 返回结构说明

成功返回 `{ok:true, data:{...}}`，失败返回 `{ok:false, error:{code, message}}`。

**data 字段**：
字段 类型 说明
------------------
carrier string 快递100 编码（如 zhongtong / shunfeng）
carrierName string 中文名称（如 中通快递 / 顺丰速运）
number string 实际查询到的运单号
status string 标准状态码：pending（揽收） / transit（在途） / delivered（已签收） / exception（退回/拒收/问题件） / unknown
statusText string 中文状态描述
events[] array 轨迹数组（时间倒序）
events[].time string 轨迹时间 "YYYY-MM-DD HH:mm:ss"
events[].description string 轨迹内容描述
events[].location string? 所在地点（部分快递公司缺失）
queriedAt number 本服务查询时间戳（秒）
source string 上游数据源标识（固定为 "kuaidi100"）

🎯 直接试用

快递查询 · 实时返回

不传 carrier 自动识别，不支持纯数字歧义单号
等待查询...

⚠️ 错误码

codeHTTP说明
INVALID_PARAM 400 运单号缺失 / 太短 / carrier 不支持
NO_CARRIER 400 无法自动识别快递公司，请手动指定 carrier
NO_DATA 404 暂未查询到物流信息（单号不存在、刚寄出未揽收、或快递公司无公开轨迹）
RATE_LIMITED 429 请求过于频繁，本 IP 每分钟最多 30 次
UPSTREAM_TIMEOUT 502 快递100 上游超时
UPSTREAM_ERROR 502 快递100 返回业务错误
NOT_CONFIGURED 503 未配置快递查询密钥（本接口当前不需要）

⏱ 限流策略

同一 IP 每分钟最多 30 次请求（含缓存命中）。超限返回 HTTP 429 + 中文提示

💾 缓存策略

同一运单号结果缓存 10 分钟（KV TRACK_CACHE）。缓存命中不计入上游请求量，但会计入限流计数

📝 额外说明

**自动识别规则**（基于单号前缀 + 长度，无需查数据库）：

 规则  识别为 
--------------
 SF 前缀 / 15 位 / 12 位首位 10/12/15/18  顺丰 shunfeng 
 14 位纯数字 / 12 位首位 2/7  中通 zhongtong 
 13 位首位 1/4/5 / 15 位  韵达 yunda 
 YT/YTO 前缀 / 12 位首位 1/2/5/8/9  圆通 yuantong 
 ST 前缀 / 12 位首位 2/4/7  申通 shentong 
 JT 前缀 / 13 位首位 7 / 15 位首位 3  极兔 jtexpress 
 JD/LB/V 前缀  京东物流 jd 
 EE/EA/EH 前缀  EMS ems 
 99 前缀  邮政快递包裹 youzhengguonei 
 DBL/DPK 前缀  德邦快递 debangkuaidi 
 CN 前缀  菜鸟速递 danniao 
 KY 前缀  跨越速运 kuayue 
 AN 前缀  安能快运 annengwuliu 
 ZJS 前缀  宅急送 zhaijisong 
 DT/DD 前缀  天天快递 tiantian 

> 有前缀命中 → unique 唯一识别；无前缀纯数字多规则命中 → ambiguous 返回候选列表让你手动指定；无规则命中 → NO_CARRIER。

**carrier 别名**：支持中文（顺丰、中通、圆通、韵达、京东、申通、EMS、邮政、宅急送、天天、德邦、百世、跨越、极兔、菜鸟、安能）和缩写（sf、zto、yto、jd、st、zt、yt、dt、zjs）。注意：宅急送编码是 zhaijisong，但传 carrier=zjs 也能自动映射。

**数据来源与兜底策略**：
- 主源：快递100 公开查询接口（www.kuaidi100.com/query），无需任何 Key
- 商业源（可选）：如果配置了 `KUAIDI100_KEY` + `KUAIDI100_CUSTOMER`，优先走商业接口（api.kuaidi100.com），失败再降级到公开接口
- 超时保护：单次请求 5 秒，Provider 链总耗时 ≤ 12 秒
- 负缓存：同一单号同一源失败后 60 秒内不重打（KV 记录），避免连续被限流
- **天天快递 tiantian**：公开接口彻底关闭（返回"参数错误"），无任何免费公开查询源可用。显式指定 carrier=tiantian 会返回 CARRIER_UNAVAILABLE 错误并说明原因。
- **宅急送**：编码是 zhaijisong（不是 zjs），公开查询可用。
- 共 20 家：18 家公开可用 + 1 家需商业 Key（天天）+ 1 家无任何公开源（已关闭）

完整 carrier 清单和 availability 状态见 /carriers 接口返回。