252 lines
5.7 KiB
Markdown
252 lines
5.7 KiB
Markdown
# 快递100查询问题排查指南
|
||
|
||
## 问题现象
|
||
|
||
查询京东快递单号 `JD0230761381812` 时，快递100返回错误：
|
||
```
|
||
"找不到对应公司" (returnCode: 400)
|
||
```
|
||
|
||
但在京东官网可以正常查询到物流信息。
|
||
|
||
---
|
||
|
||
## 问题原因
|
||
|
||
### 1. 快递100账号权限限制
|
||
|
||
快递100的不同套餐支持的快递公司数量不同：
|
||
- **基础版**：支持常用的10-20家快递公司
|
||
- **标准版**：支持50+家快递公司
|
||
- **企业版**：支持100+家快递公司
|
||
|
||
你的账号可能是基础版，不包含京东快递的查询权限。
|
||
|
||
### 2. 快递公司编码问题
|
||
|
||
快递100对某些快递公司有特殊的编码要求：
|
||
- 京东快递：`jingdong`（不是 `jd`）
|
||
- 极兔速递：`jtexpress`（不是 `jt`）
|
||
- 顺丰速运：`shunfeng`（不是 `sf`）
|
||
|
||
### 3. 需要额外开通
|
||
|
||
某些快递公司需要在快递100后台单独开通才能查询。
|
||
|
||
---
|
||
|
||
## 解决方案
|
||
|
||
### 方案一：升级快递100套餐（推荐）
|
||
|
||
1. 登录快递100后台：https://www.kuaidi100.com/
|
||
2. 进入"套餐管理"
|
||
3. 升级到支持更多快递公司的套餐
|
||
4. 或单独开通京东快递查询权限
|
||
|
||
### 方案二：使用官网查询（当前可用）
|
||
|
||
系统已经提供了官网查询链接作为备用方案：
|
||
|
||
**京东物流官网：**
|
||
```
|
||
https://www.jdl.com/#/trackQuery?waybillCode=JD0230761381812
|
||
```
|
||
|
||
**使用步骤：**
|
||
1. 在订单详情页面
|
||
2. 点击"京东物流查件"链接
|
||
3. 自动跳转到京东官网查询页面
|
||
4. 查看完整的物流轨迹
|
||
|
||
### 方案三：联系快递100客服
|
||
|
||
如果确认套餐应该支持但仍然查询失败：
|
||
|
||
1. 联系快递100客服
|
||
2. 提供你的 Customer ID
|
||
3. 说明查询失败的快递公司
|
||
4. 请求开通相应权限
|
||
|
||
**快递100客服：**
|
||
- 官网：https://www.kuaidi100.com/
|
||
- 在线客服：工作日 9:00-18:00
|
||
|
||
### 方案四：使用自动识别
|
||
|
||
某些情况下，使用 `com=auto` 自动识别可能比指定快递公司更有效：
|
||
|
||
```php
|
||
$paramArr = [
|
||
'com' => 'auto', // 自动识别
|
||
'num' => 'JD0230761381812',
|
||
'resultv2' => '1',
|
||
];
|
||
```
|
||
|
||
---
|
||
|
||
## 当前系统优化
|
||
|
||
系统已经做了以下优化：
|
||
|
||
### 1. 改进错误提示
|
||
|
||
当快递100返回"找不到对应公司"时，系统会提示：
|
||
```
|
||
"快递100暂不支持该快递公司或编码错误，请使用下方官网链接查询"
|
||
```
|
||
|
||
### 2. 提供官网链接
|
||
|
||
无论快递100是否可用，系统都会提供官网查询链接：
|
||
- 顺丰速运官网
|
||
- 京东物流官网
|
||
- 极兔速递官网
|
||
|
||
### 3. 记录详细日志
|
||
|
||
系统会记录快递100的错误信息，方便排查：
|
||
```php
|
||
Log::info('ExpressTrackService kuaidi100 business fail', [
|
||
'message' => '找不到对应公司',
|
||
'returnCode' => '400',
|
||
'num' => 'JD0230761381812',
|
||
'com' => 'jingdong'
|
||
]);
|
||
```
|
||
|
||
---
|
||
|
||
## 测试步骤
|
||
|
||
### 1. 确认快递100配置
|
||
|
||
```bash
|
||
cd server
|
||
php check_logistics_config.php
|
||
```
|
||
|
||
应该显示：
|
||
```
|
||
✅ 配置正确！快递100应该可以正常使用
|
||
```
|
||
|
||
### 2. 测试API调用
|
||
|
||
```bash
|
||
php debug_kuaidi100.php
|
||
```
|
||
|
||
查看快递100的实际响应。
|
||
|
||
### 3. 测试自动识别
|
||
|
||
```bash
|
||
php test_auto_detect.php
|
||
```
|
||
|
||
尝试使用自动识别功能。
|
||
|
||
### 4. 前端测试
|
||
|
||
1. 打开业务订单详情
|
||
2. 填写快递单号：`JD0230761381812`
|
||
3. 快递公司选择"京东快递"
|
||
4. 点击"查询物流"
|
||
5. 如果失败，点击"京东物流查件"链接
|
||
|
||
---
|
||
|
||
## 快递100支持的快递公司
|
||
|
||
### 常见快递公司编码
|
||
|
||
| 快递公司 | 快递100编码 | 是否需要手机号 |
|
||
|---------|------------|--------------|
|
||
| 顺丰速运 | shunfeng | 是（后4位） |
|
||
| 京东快递 | jingdong | 否 |
|
||
| 极兔速递 | jtexpress | 否 |
|
||
| 中通快递 | zhongtong | 否 |
|
||
| 圆通速递 | yuantong | 否 |
|
||
| 申通快递 | shentong | 否 |
|
||
| 韵达快递 | yunda | 否 |
|
||
| 百世快递 | huitongkuaidi | 否 |
|
||
| EMS | ems | 否 |
|
||
| 邮政包裹 | youzhengguonei | 否 |
|
||
|
||
### 查询完整列表
|
||
|
||
访问快递100官方文档：
|
||
https://api.kuaidi100.com/document/5f0ffb5ebc8da837cbd8aefc/5f0ffc3cbc8da837cbd8afc0
|
||
|
||
---
|
||
|
||
## 常见错误码
|
||
|
||
| 错误码 | 说明 | 解决方案 |
|
||
|-------|------|---------|
|
||
| 400 | 找不到对应公司 | 检查快递公司编码或升级套餐 |
|
||
| 500 | 服务器错误 | 稍后重试 |
|
||
| 600 | 您不是合法的订阅者 | 检查 Customer 和 Key |
|
||
| 601 | SIGN签名错误 | 检查签名算法 |
|
||
| 700 | 订阅数据已达上限 | 升级套餐或等待重置 |
|
||
| 701 | 快递公司参数异常 | 检查 com 参数 |
|
||
| 702 | 快递单号参数异常 | 检查 num 参数 |
|
||
| 703 | 查询无结果 | 快递可能未揽收 |
|
||
| 704 | 快递公司识别失败 | 使用自动识别或指定公司 |
|
||
|
||
---
|
||
|
||
## 建议
|
||
|
||
### 短期方案（立即可用）
|
||
|
||
使用官网查询链接：
|
||
- 系统已经提供了所有快递公司的官网链接
|
||
- 用户点击即可跳转查询
|
||
- 无需额外配置
|
||
|
||
### 长期方案（推荐）
|
||
|
||
1. **升级快递100套餐**
|
||
- 支持更多快递公司
|
||
- 提供更好的用户体验
|
||
- 统一的查询接口
|
||
|
||
2. **对接多个物流API**
|
||
- 快递100作为主要渠道
|
||
- 各快递公司官方API作为备用
|
||
- 自动切换，提高成功率
|
||
|
||
3. **缓存查询结果**
|
||
- 减少API调用次数
|
||
- 降低费用
|
||
- 提高响应速度
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
当前问题是快递100账号不支持京东快递查询，但系统已经提供了官网查询链接作为备用方案。
|
||
|
||
**用户可以：**
|
||
1. 点击"京东物流查件"链接查询
|
||
2. 联系快递100升级套餐
|
||
3. 等待系统对接京东官方API
|
||
|
||
**系统已优化：**
|
||
1. 改进错误提示
|
||
2. 提供官网链接
|
||
3. 记录详细日志
|
||
4. 支持多种查询方式
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- `LOGISTICS_INTEGRATION_GUIDE.md` - 物流集成指南
|
||
- `LOGISTICS_UPDATE_README.md` - 更新说明
|
||
- `JTEXPRESS_SUPPORT_ADDED.md` - 极兔速递支持
|
||
- 快递100官方文档：https://api.kuaidi100.com/
|