Express Tracker（快递物流查询）
Track packages from 200+ carriers (Chinese domestic + international) via Kuaidi100 API.
Setup (Required)
Users must obtain their own Kuaidi100 API credentials:
- 1. Register at Kuaidi100 Open Platform
- 注册企业版账号（个人也可注册）
- Free tier: 100 queries/day after verification
- 2. Get credentials from the Kuaidi100 Dashboard:
-
授权 Key（API Key）: Found in 授权信息 → 授权key
-
Customer ID: Found in 授权信息 → customer
- 3. Set environment variables:
CODEBLOCK0
For persistent config, add to ~/.bashrc or ~/.zshrc:
CODEBLOCK1
Usage
CODEBLOCK2
Examples
CODEBLOCK3
How It Works
- 1. Carrier auto-detection: Local rule-based matching by tracking number prefix/length/format
- API query: Sends signed request to Kuaidi100 poll API with
resultv2=4 for advanced status - Output: Formatted timeline with full tracking history (newest first)
Supported Carriers (Auto-Detection)
| Prefix/Pattern | Carrier | Code |
|---|
| INLINECODE3 | 顺丰速运 | INLINECODE4 |
| INLINECODE5 |
圆通速递 |
yuantong |
|
JT /
J0 | 极兔速递 |
jitu |
|
JD | 京东快递 |
jd |
|
CN | 菜鸟速递 |
cainiao |
|
DPK | 德邦快递 |
debangkuaidi |
|
KYE | 跨越速运 |
kuayue |
|
AN | 安能物流 |
annengwuliu |
|
1Z | UPS |
ups |
|
78/73/72/21/68 + digits | 中通快递 |
zhongtong |
|
10/11/12/13/19/46 + 13 digits | 韵达快递 |
yunda |
|
77/88/66/55/44 + 13-15 digits | 申通快递 |
shentong |
|
E + letter + 9 digits + 2 letters | EMS |
ems |
If auto-detection fails, specify the carrier code manually as the second argument.
Full carrier code list: Kuaidi100 Carrier Codes
Dependencies
- -
curl — HTTP requests - INLINECODE31 — JSON parsing (install:
brew install jq / apt install jq) - INLINECODE34 or
md5sum or md5 — MD5 signature (at least one required)
Error Codes
| Code | Meaning | Action |
|---|
| 400 | Incomplete data / wrong carrier | Check carrier code |
| 408 |
Phone verification failed | SF/ZTO require phone number |
| 500 | No tracking info found | Verify tracking number and carrier |
| 503 | Signature verification failed | Check API Key and Customer ID |
| 601 | API Key expired / no balance | Recharge account |
Agent Integration
When a user provides a tracking number, run:
CODEBLOCK4
Parse the output and present the tracking timeline to the user. If carrier detection fails, ask the user which carrier it is.
Express Tracker（快递物流查询）
通过快递100 API追踪200多家快递公司（国内+国际）的包裹。
设置（必需）
用户必须获取自己的快递100 API凭证：
- 1. 注册 快递100开放平台
- 注册企业版账号（个人也可注册）
- 免费套餐：验证后每天100次查询
- 2. 获取凭证 从 快递100控制台：
-
授权 Key（API Key）: 在 授权信息 → 授权key 中查找
-
Customer ID: 在 授权信息 → customer 中查找
- 3. 设置环境变量：
bash
export EXPRESS
TRACKERKEY=your
apikey_here
export EXPRESS
TRACKERCUSTOMER=your
customerid_here
如需持久化配置，添加到 ~/.bashrc 或 ~/.zshrc：
bash
echo export EXPRESSTRACKERKEY=your_key >> ~/.zshrc
echo export EXPRESSTRACKERCUSTOMER=your_customer >> ~/.zshrc
使用方法
bash
自动检测快递公司并查询
scripts/track.sh <运单号>
手动指定快递公司
scripts/track.sh <运单号> <快递公司代码>
示例
bash
自动检测（推荐）
scripts/track.sh 770308811947591
明确指定快递公司
scripts/track.sh SF1234567890 shunfeng
工作原理
- 1. 快递公司自动检测：基于运单号前缀/长度/格式的本地规则匹配
- API查询：向快递100轮询API发送签名请求，使用resultv2=4获取高级状态
- 输出：格式化时间线，显示完整追踪历史（最新在前）
支持的快递公司（自动检测）
| 前缀/模式 | 快递公司 | 代码 |
|---|
| SF | 顺丰速运 | shunfeng |
| YT |
圆通速递 | yuantong |
| JT / J0 | 极兔速递 | jitu |
| JD | 京东快递 | jd |
| CN | 菜鸟速递 | cainiao |
| DPK | 德邦快递 | debangkuaidi |
| KYE | 跨越速运 | kuayue |
| AN | 安能物流 | annengwuliu |
| 1Z | UPS | ups |
| 78/73/72/21/68 + 数字 | 中通快递 | zhongtong |
| 10/11/12/13/19/46 + 13位数字 | 韵达快递 | yunda |
| 77/88/66/55/44 + 13-15位数字 | 申通快递 | shentong |
| E + 字母 + 9位数字 + 2个字母 | EMS | ems |
如果自动检测失败，请手动指定快递公司代码作为第二个参数。
完整快递公司代码列表：快递100快递公司代码
依赖项
- - curl — HTTP请求
- jq — JSON解析（安装：brew install jq / apt install jq）
- openssl 或 md5sum 或 md5 — MD5签名（至少需要一个）
错误代码
| 代码 | 含义 | 操作 |
|---|
| 400 | 数据不完整/快递公司错误 | 检查快递公司代码 |
| 408 |
手机验证失败 | 顺丰/中通需要手机号 |
| 500 | 未找到物流信息 | 验证运单号和快递公司 |
| 503 | 签名验证失败 | 检查API Key和Customer ID |
| 601 | API Key过期/余额不足 | 充值账户 |
代理集成
当用户提供运单号时，运行：
bash
EXPRESSTRACKERKEY=$KEY EXPRESSTRACKERCUSTOMER=$CUSTOMER scripts/track.sh <号码>
解析输出并向用户展示物流时间线。如果快递公司检测失败，询问用户是哪家快递公司。
