267 lines
5.6 KiB
Markdown
267 lines
5.6 KiB
Markdown
# 物流查询集成指南
|
|
|
|
## 当前实现
|
|
|
|
系统已集成快递100 API，支持顺丰速运和京东快递的物流轨迹查询。
|
|
|
|
### 查询方式优先级
|
|
|
|
1. **快递100 API**（推荐）- 实时查询物流轨迹
|
|
2. **官网链接跳转**（备用）- 未配置API时使用
|
|
|
|
---
|
|
|
|
## 快递100 API 配置（推荐）
|
|
|
|
### 1. 注册快递100账号
|
|
|
|
访问：https://www.kuaidi100.com/
|
|
- 注册企业账号
|
|
- 申请API接口权限
|
|
- 获取 `customer` 和 `key`
|
|
|
|
### 2. 配置环境变量
|
|
|
|
在 `server/.env` 文件中添加：
|
|
|
|
```env
|
|
# 快递100配置
|
|
LOGISTICS_KUAIDI100_ENABLE=true
|
|
LOGISTICS_KUAIDI100_CUSTOMER=你的customer
|
|
LOGISTICS_KUAIDI100_KEY=你的key
|
|
LOGISTICS_KUAIDI100_QUERY_URL=https://poll.kuaidi100.com/poll/query.do
|
|
```
|
|
|
|
### 3. 配置文件
|
|
|
|
在 `server/config/logistics.php` 中：
|
|
|
|
```php
|
|
<?php
|
|
|
|
return [
|
|
'kuaidi100' => [
|
|
'enable' => env('LOGISTICS_KUAIDI100_ENABLE', false),
|
|
'customer' => env('LOGISTICS_KUAIDI100_CUSTOMER', ''),
|
|
'key' => env('LOGISTICS_KUAIDI100_KEY', ''),
|
|
'query_url' => env('LOGISTICS_KUAIDI100_QUERY_URL', 'https://poll.kuaidi100.com/poll/query.do'),
|
|
],
|
|
];
|
|
```
|
|
|
|
### 4. 支持的快递公司
|
|
|
|
- **顺丰速运** (sf / shunfeng)
|
|
- **京东快递** (jd)
|
|
- 更多快递公司可通过快递100文档查询编码
|
|
|
|
---
|
|
|
|
## 官网查询链接（备用方案）
|
|
|
|
当未配置快递100 API时，系统会提供官网查询链接：
|
|
|
|
### 顺丰速运
|
|
- 链接格式：`https://www.sf-express.com/cn/sc/dynamic_function/waybill/#search/bill-number/{运单号}`
|
|
- 特点：需要输入收件人手机号后4位验证
|
|
|
|
### 京东物流
|
|
- 链接格式：`https://www.jdl.com/#/trackQuery?waybillCode={运单号}`
|
|
- 特点：直接查询，无需验证
|
|
|
|
---
|
|
|
|
## 使用说明
|
|
|
|
### 前端查询界面
|
|
|
|
位置：`业务订单详情` → `物流轨迹`
|
|
|
|
功能：
|
|
1. 选择快递公司（自动识别/顺丰/京东）
|
|
2. 点击"查询物流"按钮
|
|
3. 查看实时物流轨迹
|
|
4. 备用：点击"顺丰官网查件"或"京东物流查件"
|
|
|
|
### 自动识别规则
|
|
|
|
系统会根据运单号自动识别快递公司：
|
|
- 顺丰：以 `SF` 开头
|
|
- 京东：以 `JD`、`JDV`、`JDK`、`JDEX` 开头
|
|
|
|
### 物流状态说明
|
|
|
|
- **0** - 在途
|
|
- **1** - 揽收
|
|
- **2** - 疑难
|
|
- **3** - 已签收
|
|
- **4** - 退签
|
|
- **5** - 派件中
|
|
- **6** - 退回
|
|
- **7** - 转投
|
|
- **10** - 待清关
|
|
- **11** - 清关中
|
|
- **12** - 已清关
|
|
- **13** - 清关异常
|
|
- **14** - 收件人拒签
|
|
|
|
---
|
|
|
|
## 顺丰查询注意事项
|
|
|
|
### 为什么查不到顺丰快递？
|
|
|
|
1. **手机号验证**
|
|
- 顺丰查询需要收件人手机号后4位
|
|
- 系统已自动传入订单中的收件人手机号
|
|
- 如果查询失败，请检查订单中的手机号是否正确
|
|
|
|
2. **运单号格式**
|
|
- 确保运单号正确无误
|
|
- 顺丰运单号通常以 `SF` 开头
|
|
|
|
3. **快递100配置**
|
|
- 确认已正确配置 `LOGISTICS_KUAIDI100_*` 环境变量
|
|
- 确认快递100账户余额充足
|
|
|
|
4. **官网查询**
|
|
- 如果API查询失败，可使用官网链接
|
|
- 官网查询需要手动输入手机号后4位
|
|
|
|
---
|
|
|
|
## 扩展其他快递公司
|
|
|
|
### 1. 修改 ExpressTrackService.php
|
|
|
|
在 `resolveCarrier` 方法中添加新的快递公司识别：
|
|
|
|
```php
|
|
if ($ec === 'ems') {
|
|
return ['carrier' => 'ems', 'kuaidi_com' => 'ems', 'label' => 'EMS'];
|
|
}
|
|
```
|
|
|
|
### 2. 添加官网链接
|
|
|
|
在 `officialUrls` 方法中添加：
|
|
|
|
```php
|
|
return [
|
|
'sf' => '...',
|
|
'jd' => '...',
|
|
'ems' => 'https://www.ems.com.cn/queryList?mailNum=' . $enc,
|
|
];
|
|
```
|
|
|
|
### 3. 更新前端选项
|
|
|
|
在 `order_list.vue` 中添加选项：
|
|
|
|
```vue
|
|
<el-option label="EMS" value="ems" />
|
|
```
|
|
|
|
---
|
|
|
|
## 故障排查
|
|
|
|
### 问题1：提示"未配置快递100查询密钥"
|
|
|
|
**解决方案：**
|
|
1. 检查 `.env` 文件中的配置
|
|
2. 确认 `LOGISTICS_KUAIDI100_ENABLE=true`
|
|
3. 重启服务器
|
|
|
|
### 问题2：查询返回"查询失败"
|
|
|
|
**可能原因：**
|
|
1. 运单号错误
|
|
2. 快递尚未揽收
|
|
3. 快递100账户余额不足
|
|
4. 手机号后4位不匹配（顺丰）
|
|
|
|
**解决方案：**
|
|
1. 核对运单号
|
|
2. 等待快递揽收后再查询
|
|
3. 充值快递100账户
|
|
4. 使用官网链接手动查询
|
|
|
|
### 问题3：顺丰查询失败但京东正常
|
|
|
|
**原因：**
|
|
顺丰查询需要手机号后4位验证
|
|
|
|
**解决方案：**
|
|
1. 确保订单中填写了正确的收件人手机号
|
|
2. 使用官网链接，手动输入手机号后4位
|
|
|
|
---
|
|
|
|
## API 接口说明
|
|
|
|
### 查询物流轨迹
|
|
|
|
**接口：** `GET /tcm.prescriptionOrder/logisticsTrace`
|
|
|
|
**参数：**
|
|
- `id` (必填): 业务订单ID
|
|
- `express_company` (可选): 快递公司 (auto/sf/jd)
|
|
|
|
**返回示例：**
|
|
|
|
```json
|
|
{
|
|
"carrier": "sf",
|
|
"carrier_label": "顺丰速运",
|
|
"kuaidi_com": "shunfeng",
|
|
"traces": [
|
|
{
|
|
"time": "2024-01-15 10:30:00",
|
|
"context": "快件已签收"
|
|
},
|
|
{
|
|
"time": "2024-01-15 08:00:00",
|
|
"context": "派件中"
|
|
}
|
|
],
|
|
"state": "3",
|
|
"state_text": "已签收",
|
|
"source": "kuaidi100",
|
|
"hint": "",
|
|
"official_url": "https://www.sf-express.com/...",
|
|
"official_urls": {
|
|
"sf": "https://www.sf-express.com/...",
|
|
"jd": "https://www.jdl.com/..."
|
|
},
|
|
"tracking_number": "SF1234567890",
|
|
"express_company_used": "sf"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 费用说明
|
|
|
|
### 快递100 API
|
|
|
|
- 按查询次数计费
|
|
- 具体价格请咨询快递100官方
|
|
- 建议：配置后台缓存减少重复查询
|
|
|
|
### 官网查询
|
|
|
|
- 完全免费
|
|
- 需要用户手动跳转
|
|
- 顺丰需要手机号验证
|
|
|
|
---
|
|
|
|
## 更新日志
|
|
|
|
### 2024-01-15
|
|
- 更新顺丰官网查询链接（新版）
|
|
- 更新京东物流查询链接
|
|
- 优化手机号后4位自动传入逻辑
|
|
- 完善错误提示信息
|