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

技能元数据#

属性值名称批量快递查询API-快递鸟Slugkdniaoapi-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_KEYAPI异常检查凭证配置，建议稍后重试没有可用套餐需在快递鸟官网开通套餐

---

使用示例#

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