# 快递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/