← Back to Skills Marketplace
15814059255

批量快递查询API-快递鸟

by kdnaio · GitHub ↗ · v1.0.0 · MIT-0
cross-platform ✓ Security Clean
116
Downloads
1
Stars
0
Active Installs
1
Versions
Install in OpenClaw
/install kdniaoapi-skill
Description
支持通过快递鸟API实时查询运单轨迹信息；当用户需要查询快递物流状态、追踪运单进度或获取包裹配送详情时使用
README (SKILL.md)

快递鸟运单查询

任务目标

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

前置准备

依赖安装

  • Python依赖：requests>=2.28.0
  • 安装命令： 
    pip install requests>=2.28.0

凭证配置

必需环境变量：

  • KUAIDI_BIRD_API_CREDENTIALS：快递鸟API凭证

凭证格式：

CUSTOMER_CODE|APP_KEY

格式说明：

  • 使用竖线（|）分隔商户ID和API密钥
  • 商户ID（CUSTOMER_CODE）：快递鸟账号的唯一标识
  • API密钥（APP_KEY）：用于API请求签名的密钥

获取方式：

  1. 访问快递鸟官网（https://www.kdniao.com/）注册账号
  2. 登录后进入"API管理"或"开发者中心"
  3. 在商户信息中获取商户ID（CUSTOMER_CODE）
  4. 在API密钥管理中获取API密钥（APP_KEY）
  5. 使用竖线（|）拼接两个值作为环境变量值

配置示例：

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

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

# Windows CMD
set KUAIDI_BIRD_API_CREDENTIALS=1292092|703d0b97-07fa-478c-bfea-ca3597f2ce0f

套餐要求

快递鸟账号需开通快递查询服务套餐（免费或付费）

安全建议

  • 妥善保管API密钥，避免泄露到代码仓库或公共平台
  • 建议使用环境变量或密钥管理工具存储凭证
  • 在生产环境使用前，先在测试环境验证
  • 定期检查API调用额度和使用情况
  • 不要在脚本中硬编码凭证

操作步骤

标准流程

  1. 确认运单信息

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

  2. 执行查询

    • 调用 scripts/query_tracking.py 处理运单查询
    • 参数说明：
      • --logistic-code：运单号（必需）
      • --api-url：API地址（可选，默认为快递鸟正式环境）
    • 示例： 
      python /workspace/projects/kuaidi-bird-tracking/scripts/query_tracking.py --logistic-code 773367326370601

  3. 解析与展示结果

    • 脚本返回结构化的JSON结果
    • 智能体解析返回数据，提取关键信息：
      • 物流状态（已揽收、运输中、派送中、已签收等）
      • 轨迹时间线（按时间顺序的物流节点）
      • 当前最新状态
    • 以自然语言向用户展示查询结果

可选分支

  • 当 运单号无效或不存在：提示用户检查运单号是否正确
  • 当 提示"缺少快递鸟API凭证配置"：检查环境变量 KUAIDI_BIRD_API_CREDENTIALS 是否已正确设置
  • 当 提示"凭证解析失败"：确认凭证格式为 CUSTOMER_CODE|APP_KEY，使用竖线（|）分隔
  • 当 查询失败或API异常：检查凭证配置，确认账号套餐状态，建议稍后重试
  • 当 提示"没有可用套餐"：说明快递鸟账号未开通查询服务，需在快递鸟官网开通套餐
  • 当 物流信息为空：说明该运单暂无轨迹更新

资源索引

  • 必要脚本：见 scripts/query_tracking.py（用途：调用快递鸟API查询运单轨迹；参数：运单号、API地址）

注意事项

环境变量配置

  • 必需环境变量：KUAIDI_BIRD_API_CREDENTIALS
  • 格式要求：CUSTOMER_CODE|APP_KEY（使用竖线分隔）
  • 配置示例： 
    export KUAIDI_BIRD_API_CREDENTIALS="1292092|703d0b97-07fa-478c-bfea-ca3597f2ce0f"

API使用

  • 本Skill使用快递鸟API，需要先配置商户ID和API密钥
  • 默认使用快递鸟正式环境API地址（https://api.kdniao.com/api/dist）
  • 快递鸟账号需开通快递查询服务套餐（免费或付费），否则会提示"没有可用套餐"

安全建议

  • 妥善保管API密钥，避免泄露到代码仓库或公共平台
  • 建议使用环境变量或密钥管理工具存储凭证
  • 在生产环境使用前，先在测试环境验证
  • 定期检查API调用额度和使用情况
  • 脚本代码简短清晰，建议在使用前阅读并理解其逻辑
  • 环境变量使用清晰命名（KUAIDI_BIRD_API_CREDENTIALS），易于理解和维护

其他

  • 不同快递公司的查询结果格式可能略有差异
  • 建议在查询前提醒用户确认运单号准确性

使用示例

示例1：查询顺丰运单

  • 功能说明：查询顺丰快递的物流轨迹
  • 执行方式：脚本查询 + 智能体解析展示
  • 关键参数：运单号 SF1234567890
  • 执行： 
    python /workspace/projects/kuaidi-bird-tracking/scripts/query_tracking.py --logistic-code SF1234567890
  • 结果：智能体展示"包裹已揽收→运输中→派送中→已签收"的完整轨迹

示例2：查询圆通运单

  • 功能说明：查询圆通速递的物流状态
  • 执行方式：脚本查询 + 智能体解析展示
  • 关键参数：运单号 YT1234567890123
  • 执行： 
    python /workspace/projects/kuaidi-bird-tracking/scripts/query_tracking.py --logistic-code YT1234567890123
  • 结果：智能体展示当前物流状态和最新物流节点

示例3：批量查询

  • 功能说明：依次查询多个运单的物流信息
  • 执行方式：循环调用脚本
  • 执行：智能体依次处理每个运单号，汇总展示结果
Usage Guidance
This skill appears to do what it says: it calls the 快递鸟 (Kdniao) API using a single API credential stored in KUAIDI_BIRD_API_CREDENTIALS (format CUSTOMER_CODE|APP_KEY). Before installing, verify the registry metadata is updated to declare that env var (a packaging omission), review the included script (it's short and readable), and ensure you: (1) provide only valid service credentials via environment variables (do not hard-code them), (2) avoid pasting real API keys into public examples or logs, and (3) confirm your environment can make outbound HTTPS calls to https://api.kdniao.com. If you want extra assurance, run the script locally with a test account first. Confidence in this assessment is high given the clear one-to-one mapping between purpose, docs, and code.
Capability Analysis
Type: OpenClaw Skill Name: kdniaoapi-skill Version: 1.0.0 The skill is a legitimate tool for querying express delivery tracking information via the Kuaidi Bird API. The script `scripts/query_tracking.py` correctly handles API authentication using environment variables and communicates only with the official endpoint (api.kdniao.com). No evidence of data exfiltration, malicious execution, or prompt injection was found.
Capability Assessment
ℹ Purpose & Capability
The skill's name, description, SKILL.md, and the included script consistently implement real-time queries to the 快递鸟 (Kdniao) API and require an API credential (CUSTOMER_CODE|APP_KEY). However, registry metadata at the top of the submission lists no required environment variables while SKILL.md and the script require KUAIDI_BIRD_API_CREDENTIALS — this mismatch is likely a packaging/metadata omission rather than malicious.
✓ Instruction Scope
SKILL.md describes installing requests, setting the KUAIDI_BIRD_API_CREDENTIALS env var, passing a logistic-code argument, and delegating to scripts/query_tracking.py. The instructions do not ask the agent to read unrelated files, other env vars, or send data to unexpected endpoints; the script posts to the documented https://api.kdniao.com/api/dist endpoint and prints structured JSON results.
✓ Install Mechanism
There is no automated install spec (instruction-only), and dependencies are a single standard Python package (requests). No arbitrary downloads, extract steps, or non-standard installers are present. Risk from installation is low.
✓ Credentials
The skill requires a single service credential (KUAIDI_BIRD_API_CREDENTIALS in format CUSTOMER_CODE|APP_KEY) which is proportional to calling the Kdniao API. The credential is used only to sign requests; no other unrelated secrets are requested. Note: SKILL.md contains an example credential value (sample) — users should avoid using real keys in examples or public repos.
✓ Persistence & Privilege
The skill does not request permanent presence (always:false) and does not modify other skills or system-wide settings. It runs as an invoked script and prints results; autonomous invocation is allowed by default but not excessive for this type of integration.
How to Use
  1. Make sure OpenClaw is installed (local or Docker)
  2. Run the install command in chat: /install kdniaoapi-skill
  3. After installation, invoke the skill by name or use /kdniaoapi-skill
  4. Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
kuaidi-bird-tracking 1.0.0 - Initial release - Provides real-time express package tracking via the Kuaidi Bird (快递鸟) API. - Supports querying and displaying shipment status, tracking progress, and delivery details. - Requires setup of the `KUAIDI_BIRD_API_CREDENTIALS` environment variable (`CUSTOMER_CODE|APP_KEY` format). - Includes clear setup, security, and usage instructions for both individual and batch waybill checks. - Uses a Python script (`scripts/query_tracking.py`) and requires the `requests>=2.28.0` package.
Metadata
Slug kdniaoapi-skill
Version 1.0.0
License MIT-0
All-time Installs 0
Active Installs 0
Total Versions 1
Frequently Asked Questions

What is 批量快递查询API-快递鸟?

支持通过快递鸟API实时查询运单轨迹信息；当用户需要查询快递物流状态、追踪运单进度或获取包裹配送详情时使用. It is an AI Agent Skill for Claude Code / OpenClaw, with 116 downloads so far.

How do I install 批量快递查询API-快递鸟?

Run "/install kdniaoapi-skill" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is 批量快递查询API-快递鸟 free?

Yes, 批量快递查询API-快递鸟 is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does 批量快递查询API-快递鸟 support?

批量快递查询API-快递鸟 is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created 批量快递查询API-快递鸟?

It is built and maintained by kdnaio (@15814059255); the current version is v1.0.0.

More Skills
self-improving agent
Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Clau...
⬇ 463283 · by pskoett
Skill Vetter
Security-first skill vetting for AI agents. Use before installing any skill from ClawdHub, GitHub, or other sources. Checks for red flags, permission scope, and suspicious patterns.
⬇ 259410 · by spclaudehome
Polymarket
Query Polymarket prediction markets. Check odds, find trending markets, search events, track price movements.
⬇ 232503 · by joelchance
Self-Improving + Proactive Agent
Self-reflection + Self-criticism + Self-learning + Self-organizing memory. Agent evaluates its own work, catches mistakes, and improves permanently. Use when...
⬇ 200423 · by ivangdavila
Github
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
⬇ 191115 · by steipete
ontology
Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linkin...
⬇ 190156 · by oswalpalash

💬 Comments