PHP的Laravel框架中对接快递100物流轨迹查询接口经验总结

电商类项目离不开物流轨迹查询。快递100接口稳定、支持的快递公司全，Laravel 里接入其实不难，但有几个细节容易翻车。

把经验总结一下，按这个流程走基本不会踩坑。

01

接口选型：订阅推送 vs 主动查询

订阅推送：快递有更新时快递100主动回调你的接口，体验好但需要配置回调地址

主动查询：用户打开订单详情时调用一次，按需拉取，实现简单

如果订单量不大，先用主动查询跑通；量大了再上订阅推送，省接口费。

02

Laravel 里怎么封装

① config/services.php 里配置 key、secret、callback_url

② 独立 Service 类（比如 KuaiDi100Service），对外暴露 track() 方法，内部用 Guzzle 发请求

③ 签名算法：快递100用 MD5，key+订单号+secret 拼接后 MD5 大写，别写错顺序

④ 响应处理：JSON 解码后判断 status，失败抛自定义异常，成功返回轨迹数组

03

踩过的坑

⚠️ 快递公司编码：不是顺丰就写 SF，要查快递100的编码表，汇通是 huitongkd 不是 huitong

⚠️ 签名顺序：key+订单号+secret，三个拼完 MD5，顺序错了直接 401

⚠️ 单号格式：顺丰等部分快递公司单号有校验规则，别传错位数

⚠️ 回调接口：订阅推送要在 RouteServiceProvider 里取消 CSRF 校验，不然快递100回调被拦截

一句话总结：配置放 config、逻辑封装 Service、签名按顺序、编码查文档，Laravel 对接快递100就这四件事。