全球快递物流查询

数据由 聚合数据 提供 — 国内领先的数据服务平台，支持全球上千家快递公司跟踪服务。

输入快递单号，查询包裹的实时物流轨迹、当前状态、签收信息。

前置配置：获取 API Key

1. 前往 聚合数据官网 免费注册账号
2. 进入 全球快递物流查询 API 页面，点击「申请使用」
3. 审核通过后在「我的API」中获取 AppKey
4. 配置 Key（三选一）：

# 方式一：环境变量（推荐，一次配置永久生效）
export JUHE_EXPRESS_KEY=你的AppKey

# 方式二：.env 文件（在脚本目录创建）
echo "JUHE_EXPRESS_KEY=你的AppKey" > scripts/.env

# 方式三：每次命令行传入
python scripts/express_track.py --key 你的AppKey 快递单号

使用方法

注意：--com 为必填参数，接口不支持自动识别快递公司，必须提供快递公司编号。

基本查询

# 使用中文名称（脚本自动转换为编号后传给接口）
python scripts/express_track.py YT1234567890123 --com 圆通

# 使用快递公司编号（直接传给接口）
python scripts/express_track.py YT1234567890123 --com yt

输出示例：

📦 查询单号: YT1234567890123  快递公司: 圆通速递（yt）

────────────────────────────────────────────────────────
  🛵  圆通速递（yt）  单号: YT1234567890123
  状态: 派件中
────────────────────────────────────────────────────────
  ▶ 2026-03-24 09:30:00
      【上海市】您的快件已由快递员张三(18812345678)派出，请您注意查收

    2026-03-23 22:10:00
      【上海市】快件已到达 上海转运中心

    2026-03-23 10:05:00
      【北京市】快件已从 北京顺义分拨中心 发出
────────────────────────────────────────────────────────

需要手机号的快递（顺丰、中通、跨越等）

部分快递公司（目前包括顺丰、中通、跨越，未来可能增加）查询时需提供寄件人或收件人手机号后 4 位，二选一即可：

# 提供寄件人手机号后4位
python scripts/express_track.py SF1234567890 --com 顺丰 --sender-phone 1234

# 提供收件人手机号后4位
python scripts/express_track.py SF1234567890 --com 顺丰 --receiver-phone 5678

查看所有支持的快递公司

python scripts/express_track.py --list

搜索快递公司

python scripts/express_track.py --search 圆通
python scripts/express_track.py --search fedex

常用快递公司编号速查

完整列表（1000+ 家）请运行 python scripts/express_track.py --list 或查阅 references/express-company-list.json

AI 使用指南

当用户询问快递物流信息时，按以下步骤操作：

1. 提取查询信息 — 从用户消息中识别快递单号和快递公司
2. 确认快递公司 — --com 为必填，接口不支持自动识别。若用户未提及公司，需询问用户；若用户提供了名称，读取本地 references/express-company-list.json 查找对应编号（无需联网）
3. 处理手机尾号 — 顺丰（sf）、中通（zto）、跨越（kye）等快递需提供手机号后4位，询问用户选择提供寄件人（--sender-phone）还是收件人（--receiver-phone）手机尾号；未来可能有更多公司有此要求，遇到 204305 错误码时同样引导用户提供
4. 调用脚本 — 传入单号、--com 编号（中文名或编号均可，脚本自动转换）执行查询
5. 解读结果 — 用自然语言总结当前状态，告知用户包裹是否已签收、当前在哪

参数说明

返回字段说明

status_detail 状态枚举对照

错误处理

快递公司识别技巧

• 单号前缀参考：SF 开头 → 顺丰（sf）；YT 开头 → 圆通（yt）；STO 开头 → 申通（sto）；JD 开头 → 京东（jd）；但仅供参考，以用户确认的公司为准
• --com 为必填，接口不支持自动识别，若用户未说明快递公司，应主动询问
• 中文名/编号均可传，脚本会先在 references/express-company-list.json 本地查找对应编号，再传给接口，无需额外联网

脚本位置

scripts/express_track.py — 封装了 API 调用、公司名称模糊匹配、物流轨迹格式化输出和错误处理。

快递公司数据：references/express-company-list.json — 包含 1000+ 家全球快递公司的名称与编号对照表，无需联网，本地直接读取。

直接调用 API（无需脚本）

GET https://v.juhe.cn/exp/index?key=YOUR_KEY&com=sf&no=SF1234567890&senderPhone=1234

参数说明：

关于聚合数据

聚合数据（juhe.cn） 是国内专业的 API 数据服务平台，提供包括：

• 交通物流：快递追踪、火车时刻查询、航班动态
• 生活服务：天气预报、万年历、节假日查询
• 身份核验：手机号归属地、身份证实名验证
• 金融数据：汇率、股票、黄金价格
• 网络工具：IP查询、DNS解析

注册即可免费使用，适合个人开发者和企业接入。