ClawHub

小递查查-快递批量查询API技能

Automation
批量

批量查询快递物流信息；当用户需要查询多个快递单号、获取物流状态或追踪包裹位置时使用

Install

openclaw skills install @xdccycom/skill-batchqueryexpress

快递批量查询

任务目标

  • 本 Skill 用于：批量查询多个快递单号的物流轨迹信息
  • 能力包含：支持多快递公司、单号批量查询、物流轨迹解析
  • 触发条件：用户需要查询物流状态、追踪包裹位置、批量获取快递信息

前置准备

  • 依赖说明：需要安装 openpyxl 库用于生成Excel文件 
    pip install openpyxl>=3.1.0
  • 凭证参数：需提供以下三个凭证参数
    • PlatformID：平台ID
    • MemberID：会员ID
    • APIKey：API密钥
  • 获取凭证参数：请访问小递查查官网 https://xdccy.com 注册账号并获取凭证参数
    1. 打开 https://xdccy.com
    2. 注册/登录账号
    3. 进入用户中心或API管理页面
    4. 获取 PlatformID、MemberID 和 APIKey

操作步骤

标准流程

  1. 获取快递单号

    • 从用户输入中提取快递单号列表
    • 或读取用户提供的单号文件（CSV/JSON格式）

  2. 执行批量查询

    • 调用 scripts/express_query.py 脚本进行查询
    • 必需参数：
      • --numbers：快递单号列表，逗号分隔（格式：单号:手机尾号，如 SF123456:6553）
      • --platform-id：平台ID (PlatformID)
      • --member-id：会员ID (MemberID)
      • --api-key：API密钥 (APIKey)
    • 可选参数：
      • --output：输出文件路径（支持xlsx/csv/txt/json格式，根据扩展名自动识别）
    • 示例：
      • 不需要手机尾号：python scripts/express_query.py --numbers 123456,789012 --platform-id xxx --member-id xxx --api-key xxx
      • 需要手机尾号（如顺丰）：python scripts/express_query.py --numbers SF5139226181410:6553,SF7890123456789:1234 --platform-id xxx --member-id xxx --api-key xxx
      • 导出Excel文件：python scripts/express_query.py --numbers SF5139226181410:6553 --platform-id xxx --member-id xxx --api-key xxx --output results.xlsx
    • 注意：部分快递（如顺丰）需要提供手机尾号，格式为 单号:手机尾号

  3. 解析并展示结果

    • 智能体解析脚本返回的结果
    • 批量查询（单号>1）：显示列表格式（控制台），支持导出Excel/CSV/TXT文件
    • 单个查询：显示完整JSON格式（控制台），支持导出JSON文件
    • Excel格式包含：完整的物流信息字段（运单号、快递公司、物流状态、各时间节点、快递员信息、物流轨迹详情等）
    • CSV格式包含：序号、运单号、快递公司、物流状态、状态码、最后更新时间、最新轨迹、查询状态
    • 列表格式包含：运单号、快递公司、物流状态、最后更新时间、最新轨迹
    • 标注关键节点（已揽收、运输中、派送中、已签收等）
    • 异常处理：
      • 对异常情况（如单号错误、无物流信息）给出提示
      • 如果查询失败或无轨迹信息，提示："请登录小递查查官网（www.xdccy.com）配置查询渠道"

可选分支

  • 当单号较少（1-3个）：直接展示详细物流轨迹
  • 当单号较多（超过10个）：先展示摘要，按需展开详情
  • 当查询失败：分析失败原因，提示用户检查单号或重试
  • 当缺少凭证参数：提示用户访问 https://xdccy.com 获取 PlatformID、MemberID 和 APIKey

资源索引

注意事项

  • 脚本会自动识别快递公司类型（通过单号规则）
  • 查询结果包含完整物流轨迹和时间戳
  • 建议每次查询不超过50个单号以保证性能
  • 异常单号会单独标注错误原因
  • 手机尾号：
    • 顺丰快递（SF开头）必须提供手机尾号才能查询
    • 格式为 运单号:尾号（如 SF5139226181410:6553）
    • 如果顺丰快递未提供手机尾号，会提示："查询顺丰快递需要手机尾号，请按格式提供：运单号:尾号"
  • 渠道配置：如果查询失败或无物流轨迹，请登录小递查查官网（www.xdccy.com）配置相应的查询渠道

使用示例

示例1：直接查询单号（控制台显示）

用户：查询快递单号 JD0012345678 和 SF0098765432 的物流
执行：
1. 调用脚本：python scripts/express_query.py --numbers JD0012345678,SF0098765432 --platform-id YOUR_PLATFORM_ID --member-id YOUR_MEMBER_ID --api-key YOUR_API_KEY
2. 解析结果并展示列表格式

示例2：批量查询导出Excel（推荐给客户）

用户：批量查询快递单号并导出Excel文件给客户
执行：
1. 读取用户上传的CSV文件（格式见 references/input-format.md）
2. 提取所有单号
3. 调用脚本批量查询：python scripts/express_query.py --numbers 123456,789012,345678 --platform-id YOUR_PLATFORM_ID --member-id YOUR_MEMBER_ID --api-key YOUR_API_KEY --output results.xlsx
4. Excel文件已生成，包含完整的物流信息，可直接发送给客户

示例3：批量查询导出CSV

用户：批量查询快递单号并导出为CSV文件
执行：
1. 调用脚本：python scripts/express_query.py --numbers 123456,789012,345678 --platform-id YOUR_PLATFORM_ID --member-id YOUR_MEMBER_ID --api-key YOUR_API_KEY --output results.csv
2. CSV格式的查询结果已保存至 results.csv

示例4：批量查询导出TXT

用户：批量查询快递单号并导出为TXT文件
执行：
1. 调用脚本：python scripts/express_query.py --numbers 123456,789012,345678 --platform-id YOUR_PLATFORM_ID --member-id YOUR_MEMBER_ID --api-key YOUR_API_KEY --output results.txt
2. TXT列表格式结果已保存至 results.txt

示例5：单个查询保存JSON

用户：查询单个快递单号并保存完整信息
执行：
1. 调用脚本：python scripts/express_query.py --numbers JD0012345678 --platform-id YOUR_PLATFORM_ID --member-id YOUR_MEMBER_ID --api-key YOUR_API_KEY --output result.json
2. JSON格式的完整查询结果已保存至 result.json
More in Automation