全球快递物流查询#

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

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

---

前置配置：获取 API Key#

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

bash

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

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

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

---

使用方法#

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

基本查询#

bash

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

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

输出示例：

text

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

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

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

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

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

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

bash

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

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

查看所有支持的快递公司#

bash

python scripts/express_track.py --list

搜索快递公司#

bash

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

---

常用快递公司编号速查#

快递公司编号快递公司编号顺丰sf圆通yt申通sto中通zto韵达yd京东快递jdEMSemsEMS国际emsg德邦db宅急送zjsDHLdhlFedEx国际fedexUPS国际ups国通gt汇通（百世）ht极兔速递jtsd

完整列表（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. 解读结果 — 用自然语言总结当前状态，告知用户包裹是否已签收、当前在哪

参数说明#

参数必填说明示例快递单号是快递运单号YT1234567890123--com是快递公司中文名或编号，脚本自动转为编号传给接口顺丰 / sf--sender-phone部分必填寄件人手机号后4位，顺丰/中通/跨越等必填其一1234--receiver-phone部分必填收件人手机号后4位，顺丰/中通/跨越等必填其一5678--list否列出所有支持的快递公司及编号—--search否搜索快递公司编号圆通

返回字段说明#

字段含义示例company快递公司名称圆通速递com快递公司编号ytno运单号YT1234567890123status当前状态数字码1status_detail当前状态英文枚举（更准确，优先使用）IN_TRANSITlist物流轨迹列表[{datetime, remark, zone}]list[].datetime轨迹时间2026-03-24 09:30:00list[].remark轨迹描述快件已到达上海转运中心list[].zone所在区域上海市

status_detail 状态枚举对照#

status_detail中文含义PENDING待处理NO_RECORD无记录ERROR查询错误IN_TRANSIT运输中DELIVERING派件中SIGNED已签收REJECTED拒收退回PROBLEM疑难件INVALID无效单号TIMEOUT查询超时FAILED投递失败SEND_BACK退件中TAKING已揽件

错误处理#

情况处理方式error_code 10001/10002/10003API Key 无效或过期，引导用户至 聚合数据 重新申请error_code 10012当日免费次数已用尽，建议升级套餐error_code 204301快递公司编号错误，使用 --list 查看支持列表error_code 204302运单号格式错误，请核对单号error_code 204304暂无物流信息，可能刚揽件未录入，建议稍后再查error_code 204305该快递公司需手机尾号，引导用户提供 --sender-phone 或 --receiver-phone（顺丰/中通/跨越等）公司名称模糊匹配到多家列出候选公司，引导用户用编号精确指定

---

快递公司识别技巧#

• 单号前缀参考：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（无需脚本）#

text

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

参数说明：

参数必填类型说明key是stringAPI Keycom是string快递公司编号，只接受编码（如 sf、 yt），不接受中文no是string快递单号senderPhone否int寄件人手机号后4位，顺丰/中通/跨越等必填其一receiverPhone否int收件人手机号后4位，顺丰/中通/跨越等必填其一dtype否string返回格式： json（默认）或 xml

---

关于聚合数据#

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

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

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