新增
This commit is contained in:
Your Name
@@ -0,0 +1,251 @@
|
||||
# 快递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/
|
||||
Reference in New Issue
Block a user