zyt/LOGISTICS_INTEGRATION_GUIDE.md

物流查询集成指南

当前实现

系统已集成快递100 API，支持顺丰速运和京东快递的物流轨迹查询。

查询方式优先级

1. 快递100 API（推荐）- 实时查询物流轨迹
2. 官网链接跳转（备用）- 未配置API时使用

---

快递100 API 配置（推荐）

1. 注册快递100账号

访问：https://www.kuaidi100.com/

• 注册企业账号
• 申请API接口权限
• 获取 customer 和 key

2. 配置环境变量

在 server/.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

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 方法中添加新的快递公司识别：

if ($ec === 'ems') {
    return ['carrier' => 'ems', 'kuaidi_com' => 'ems', 'label' => 'EMS'];
}

2. 添加官网链接

在 officialUrls 方法中添加：

return [
    'sf' => '...',
    'jd' => '...',
    'ems' => 'https://www.ems.com.cn/queryList?mailNum=' . $enc,
];

3. 更新前端选项

在 order_list.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)

返回示例：

{
    "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位自动传入逻辑
• 完善错误提示信息