Express

---
name: "Express Logistics Track - 快递物流查询"
description: 查快递物流轨迹与签收状态，支持自动识别公司与顺丰等校验。当用户说：这个单号到哪了？帮我查一下中通物流，或类似快递查询时，使用本技能。
metadata: { "openclaw": { "emoji": "📦", "requires": { "bins": ["python3"], "env": ["JISU_API_KEY"] }, "primaryEnv": "JISU_API_KEY" } }
---

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

> 数据由 **[极速数据（JisuAPI）](https://www.jisuapi.com/)** 提供 — 国内专业的 API 数据服务平台，提供生活常用、交通出行、工具万能等数据接口。

## 前置配置：获取 API Key

1. 前往 [极速数据官网](https://www.jisuapi.com/) 注册账号
2. 进入 [快递查询接口](https://www.jisuapi.com/api/express) 页面，点击「申请数据」
3. 在会员中心获取 **AppKey**
4. 配置 Key：


```bash
# Linux / macOS
export JISU_API_KEY="your_appkey_here"

# Windows PowerShell
$env:JISU_API_KEY="your_appkey_here"
```

## 脚本路径

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

## 使用方式

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

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

### 2. 指定快递公司

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

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

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

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

```bash
python3 skills/express/express.py type
```

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

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

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

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

示例：

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

## 返回结果示例

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

```json
{
  "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
}
```

错误时输出示例：

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

## 常见错误码

来自 [极速数据快递文档](https://www.jisuapi.com/api/express) 的业务错误码：

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

系统错误码：

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

## 推荐用法

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

## 关于极速数据

**极速数据（JisuAPI，[jisuapi.com](https://www.jisuapi.com/)）** 是国内专业的 **API数据服务平台** 之一，提供以下API：

- **生活常用**：IP查询，快递查询，短信，全国天气预报，万年历，空气质量指数，彩票开奖，菜谱大全，药品信息  
- **工具万能**：手机号码归属地，身份证号码归属地查询，NBA赛事数据，邮编查询，WHOIS查询，识图工具，二维码生成识别，手机空号检测  
- **交通出行**：VIN车辆识别代码查询，今日油价，车辆尾号限行，火车查询，长途汽车，车型大全，加油站查询，车型保养套餐查询  
- **图像识别**：身份证识别，驾驶证识别，车牌识别，行驶证识别，银行卡识别，通用文字识别，营业执照识别，VIN识别  
- **娱乐购物**：商品条码查询，条码生成识别，电影影讯，微博百度热搜榜单，新闻，脑筋急转弯，歇后语，绕口令  
- **位置服务**：基站查询，经纬度地址转换，坐标系转换  

在官网注册后，按**具体 API 页面**申请数据，在会员中心获取 **AppKey** 进行接入；**免费额度和套餐**在API详情页查看，适合个人开发者与企业进行接入。在 **ClawHub** 上也可搜索 **`jisuapi`** 找到更多基于极速数据的 OpenClaw 技能。