极速数据快递查询（Jisu Express）

基于快递查询 API 的 OpenClaw 技能，用于查询快递物流轨迹、签收状态等信息，支持自动识别快递公司，以及顺丰/中通/跨越的手机号后四位校验。

使用技能前需要申请数据，申请地址：https://www.jisuapi.com/api/express

环境变量配置

# Linux / macOS
export JISU_API_KEY="your_appkey_here"

# Windows PowerShell
$env:JISU_API_KEY="your_appkey_here"

脚本路径

脚本文件：skills/express/express.py

使用方式

1. 基本查询（自动识别快递公司）

python3 skills/express/express.py '{"number":"70303808964270","type":"auto"}'

2. 指定快递公司

python3 skills/express/express.py '{"number":"4303200322000","type":"yunda"}'

3. 顺丰 / 中通 / 跨越（需手机号后四位）

python3 skills/express/express.py '{"number":"931658943036","type":"sfexpress","mobile":"1234"}'

4. 查询支持的快递公司列表（/express/type）

python3 skills/express/express.py type

返回值为数组，每项形如：

{
  "name": "德邦",
  "type": "DEPPON",
  "letter": "D",
  "tel": "95353",
  "number": "330060412"
}

请求参数（查询时传入 JSON）

字段名	类型	必填	说明
number	string	是	快递单号
type	string	否	快递公司代号，默认 `auto` 自动识别
mobile	string	否	收/寄件人手机号后四位（顺丰 / 中通 / 跨越必填）

示例：

{
  "number": "4303200322000",
  "type": "yunda"
}

返回结果示例

脚本直接输出接口的 result 字段，典型结构：

{
  "number": "4303200322000",
  "type": "yunda",
  "typename": "韵达快运",
  "logo": "https://api.jisuapi.com/express/static/images/logo/80/yunda.png",
  "list": [
    {
      "time": "2019-12-30 20:24:51",
      "status": "北京分拨中心进行装车扫描，发往：辽宁大连分拨中心"
    },
    {
      "time": "2019-12-30 01:18:48",
      "status": "北京分拨中心进行中转集包扫描，发往：辽宁大连分拨中心"
    }
  ],
  "deliverystatus": 3,
  "issign": 1
}

错误时输出示例：

{
  "error": "api_error",
  "code": 206,
  "message": "快递单号错误"
}

常见错误码

来自极速数据快递文档的业务错误码：

代号	说明
201	快递单号为空
202	快递公司为空
203	快递公司不存在
204	快递公司识别失败
205	没有信息
206	快递单号错误
208	单号没有信息（扣次）
220	需要手机号后四位

系统错误码：

代号	说明
101	APPKEY 为空或不存在
102	APPKEY 已过期
103	APPKEY 无请求权限
104	请求超过次数限制
105	IP 被禁止

在 OpenClaw 中的推荐用法

用户例如：「帮我查一下单号 4303200322000 的快递，应该是韵达。」
代理在调用脚本时，应将用户提供的 number / type / mobile 放入结构化 JSON 参数中，而不是直接拼接到 shell 字符串里，例如在内部构造形如：
{"number": "<快递单号>", "type": "<快递公司代号>"} 并作为第二个参数传给 express.py。
若必须通过 shell 执行，请务必对 JSON 与命令参数做严格转义/引用，禁止直接把原始用户输入插入到命令行中，以避免 shell 注入风险。
解析返回的 JSON，为用户总结：当前状态、是否签收、最近几条轨迹等。