back
loading skill details...
查询全球快递物流动态信息，支持自动识别单号，顺丰等需传手机号后四位。
---
name: tianapi-kuaidi
description: 查询全球快递物流动态信息，支持自动识别单号，顺丰等需传手机号后四位。
homepage: https://www.tianapi.com/apiview/152
metadata: {"openclaw": {"emoji": "📦", "requires": {"bins": ["python3"], "env": ["TIANAPI_KUAIDI_KEY"]}, "primaryEnv": "TIANAPI_KUAIDI_KEY"}}
---
# 天聚数行 - 快递物流查询技能
> 数据由 **<天聚数行 (TianAPI)>** 提供 — 专注开发者生态，提供涵盖生活服务、趣味娱乐及数据智能等 200+ 优质 API 接口，开箱即用，高性价比。
本技能用于查询全球快递物流的动态信息，支持自动识别单号。
---
## 前置配置：获取 API Key
1. 前往 <天聚数行官网> 免费注册账号
2. 进入 <快递物流查询 API> 页面，点击「申请接口」
3. 申请通过后，在「我的数据」中获取您的 `API Key`
4. 配置 Key（**三选一**）：
```bash
# 方式一：环境变量（推荐，一次配置永久生效）
export TIANAPI_KUAIDI_KEY=你的APIKey
# 方式二：.env 文件（在脚本目录创建）
echo "TIANAPI_KUAIDI_KEY=你的APIKey" > scripts/.env
# 方式三：每次命令行传入
python3 scripts/fetch_kuaidi.py --key 你的APIKey --number 9896725849291
```
---
## 使用方法
### 查询快递物流动态
```bash
# 查询指定快递单号的物流信息
python3 scripts/fetch_kuaidi.py <API_KEY> <NUMBER> [COMPANY] [SENDERPHONE]
```
**参数说明：**
* `<API_KEY>`: 必填，天聚数行分配的API Key。
* `<NUMBER>`: 必填，快递单号。
* `[COMPANY]`: 选填，物流公司编码（如百世汇通：huitong），带上编码查询更稳定。
* `[SENDERPHONE]`: 选填，收寄人手机尾号，目前顺丰系和中通强制要求。
**输出示例：**
📦 快递单号 9896725849291 物流信息
快递公司: 中国邮政快递/包裹/挂号信/小包
当前状态: 已签收
更新时间: 2019-11-11 16:51:12
物流轨迹:
2019-11-01 15:27:46 上海安亭网点
【嘉定安亭揽投部】安排投递,投递员:樊*亮,电话:1550****995
...
### 直接调用 API（无需脚本）
```bash
# 查询快递单号 9896725849291 的物流信息
GET https://apis.tianapi.com/kuaidi/index?key=YOUR_API_KEY&number=9896725849291
```
---
## 使用指南
当用户需要查询快递物流信息时，按以下步骤操作：
1. **识别意图**：用户想查询某个快递单号的物流动态。
2. **解析参数**：提取用户提供的快递单号、物流公司编码（可选）、手机尾号（可选）。
3. **调用脚本**：执行 `python3 scripts/fetch_kuaidi.py` 命令，传入API Key和快递单号等参数。
4. **展示结果**：解析返回的JSON数据，以清晰的格式展示物流轨迹和状态。
### 返回字段说明
| 字段 | 含义 | 示例 |
| :--- | :--- | :--- |
| time | 物流节点时间 | 2019-10-25 16:48:08 |
| status | 物流状态码 | 4 |
| address | 物流节点地址 | 嘉定安亭网点 |
| content | 物流节点详情 | 【上海市】已签收... |
| telephone | 快递公司客服电话 | 95311 |
| kuaidiname | 快递公司中文名 | 中通快递 |
| updatetime | 数据更新时间 | 2019-11-11 16:53:45 |
| enkuaidiname | 快递公司英文名 | pingyou |
### 物流状态码说明
| 状态码 | 含义 |
| :--- | :--- |
| 0 | 无记录 |
| 1 | 揽件 |
| 2 | 在途中 |
| 3 | 派送中 |
| 4 | 已签收 |
| 5 | 用户拒签 |
| 6 | 疑难件 |
| 7 | 无效单 |
| 8 | 超时单 |
| 9 | 签收失败 |
| 10 | 退回 |
| 11 | 转投 |
| 12 | 待签 |
### 错误处理
| 情况 | 处理方式 |
| :--- | :--- |
| `code: 150` | API可用次数不足，建议天聚数行控制台购买。 |
| `code: 160` | 当前未申请该API，请前往接口页面申请。 |
| `code: 230` | API密钥无效，检查 `API Key` 是否填写正确。 |
| `code: 240` | 缺少API密钥参数，检查是否传递了 `key` 参数。 |
| `code: 250` | 数据返回为空，检查快递单号是否正确。 |
| 网络超时 | 重试一次，仍失败可能为用户网络问题。 |
---
## 脚本位置
`scripts/fetch_kuaidi.py` - 封装了快递物流查询功能。
---
## 关于天聚数行
<天聚数行 (TianAPI)> 是一个致力于为个人和企业用户提供标准、简洁、高效的应用数据解决平台。API数据包括：
* **生活服务**：天气预报、快递查询、垃圾分类等
* **趣味娱乐**：土味情话、星座运势、周公解梦等
* **数据智能**：文本纠错、图像识别、机器翻译等
* **功能应用**：智能分词、坐标转换、科学计算等
* **知识问答**：古籍查询、唐诗大全、成语典故等
* **企业商务**：工商信息、条码识别、物流查询等
官网注册即可免费使用，在API市场查找数据，进入**API文档页面**一键申请数据，在控制台 - 我的密钥获取 **ApiKey** 接入，适合个人开发者和企业使用。在 **ClawHub** 上也可搜索 **`tianapi`** 找到更多天聚数行开放的 OpenClaw 技能。don't have the plugin yet? install it then click "run inline in claude" again.