zyt/KUAIDI100_TROUBLESHOOTING.md

快递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 自动识别可能比指定快递公司更有效：

$paramArr = [
    'com' => 'auto',  // 自动识别
    'num' => 'JD0230761381812',
    'resultv2' => '1',
];

---

当前系统优化

系统已经做了以下优化：

1. 改进错误提示

当快递100返回"找不到对应公司"时，系统会提示：

"快递100暂不支持该快递公司或编码错误，请使用下方官网链接查询"

2. 提供官网链接

无论快递100是否可用，系统都会提供官网查询链接：

• 顺丰速运官网
• 京东物流官网
• 极兔速递官网

3. 记录详细日志

系统会记录快递100的错误信息，方便排查：

Log::info('ExpressTrackService kuaidi100 business fail', [
    'message' => '找不到对应公司',
    'returnCode' => '400',
    'num' => 'JD0230761381812',
    'com' => 'jingdong'
]);

---

测试步骤

1. 确认快递100配置

cd server
php check_logistics_config.php

应该显示：

✅ 配置正确！快递100应该可以正常使用

2. 测试API调用

php debug_kuaidi100.php

查看快递100的实际响应。

3. 测试自动识别

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/