批量快递查询API-快递鸟

支持通过快递鸟API实时查询运单轨迹信息；当用户需要查询快递物流状态、追踪运单进度或获取包裹配送详情时使用

批量快递查询API-快递鸟 (kdniaoapi-skill)

技能元数据

属性	值
名称	批量快递查询API-快递鸟
Slug	kdniaoapi-skill
版本	v1.0.0
来源	ClawHub.ai (kdniao官方)
功能描述	支持通过快递鸟API实时查询运单轨迹信息；当用户需要查询快递物流状态、追踪运单进度或获取包裹配送详情时使用

---

任务目标

• 技能用途：查询快递运单的实时物流轨迹信息
• 能力包含：调用快递鸟API获取物流状态、解析轨迹数据、展示配送进度
• 触发条件：用户提出查询快递物流、追踪运单、查看配送状态等需求

---

前置准备

依赖安装

bash

pip install requests>=2.28.0

凭证配置

必需环境变量：KUAIDI_BIRD_API_CREDENTIALS

格式：CUSTOMER_CODE|APP_KEY（使用竖线分隔）

获取方式：

1. 访问快递鸟官网注册账号
2. 登录后进入"API管理"或"开发者中心"
3. 获取商户ID（CUSTOMER_CODE）和API密钥（APP_KEY）

配置示例：

bash

# macOS/Linux
export KUAIDI_BIRD_API_CREDENTIALS="1292092|993d0b97-07fa-478c-bfea-ca3597f2ce0f"

# Windows PowerShell
$env:KUAIDI_BIRD_API_CREDENTIALS="1292092|993d0b97-07fa-478c-bfea-ca3597f2ce0f"

---

操作步骤

标准流程

1. 确认运单信息

   • 获取用户提供的运单号
   • 验证运单号格式（通常为10-20位数字或字母数字组合）

2. 执行查询

   bash

   python3 ~/.workbuddy/skills/kdniaoapi-skill/scripts/query_tracking.py --logistic-code <运单号>
   

3. 解析与展示结果

   • 物流状态（已揽收、运输中、派送中、已签收等）
   • 轨迹时间线（按时间顺序的物流节点）
   • 当前最新状态

错误处理

场景	处理方式
运单号无效	提示用户检查运单号是否正确
缺少API凭证	检查环境变量是否已设置
凭证格式错误	确认格式为 CUSTOMER_CODE|APP_KEY
API异常	检查凭证配置，建议稍后重试
没有可用套餐	需在快递鸟官网开通套餐

---

使用示例

bash

# 查询顺丰运单
python3 ~/.workbuddy/skills/kdniaoapi-skill/scripts/query_tracking.py --logistic-code SF1234567890

# 查询圆通运单
python3 ~/.workbuddy/skills/kdniaoapi-skill/scripts/query_tracking.py --logistic-code YT1234567890123

---

注意事项

• 不同快递公司的查询结果格式可能略有差异
• 建议在查询前提醒用户确认运单号准确性
• API使用默认正式环境地址：https://api.kdniao.com/api/dist