新增
This commit is contained in:
Your Name
@@ -0,0 +1,266 @@
|
||||
# 物流查询集成指南
|
||||
|
||||
## 当前实现
|
||||
|
||||
系统已集成快递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位自动传入逻辑
|
||||
- 完善错误提示信息
|
||||
Reference in New Issue
Block a user