概述

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

技能元数据

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

任务目标

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

前置准备

依赖安装

pip install requests>=2.28.0

凭证配置

必需环境变量：KUAIDI_BIRD_API_CREDENTIALS

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

获取方式：

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

配置示例：

# 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"

操作步骤

标准流程

确认运单信息

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

执行查询

```bash

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

```

解析与展示结果

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

错误处理

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

使用示例

# 查询顺丰运单
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

版本历史

共 2 个版本

v1.0.1 当前

2026-05-19 10:57 安全安全
v1.0.0

2026-05-07 10:15 安全安全

安全检测

腾讯云安全 (Keen)

安全，无风险

查看报告

腾讯云安全 (Sanbu)