1. 项目概述最近在开发一个电商后台系统时遇到了需要实时查询物流信息的需求。经过多方对比最终选择了快递鸟的物流轨迹查询API作为解决方案。这个方案最大的优势在于支持国内主流快递公司的单号查询而且响应速度快、稳定性好。快递鸟API提供了完整的物流轨迹查询功能包括在途监控、电子面单、轨迹推送等服务。我们主要使用其在途监控功能通过单号就能获取完整的物流流转信息。下面我将详细介绍如何在PHP项目中对接这个API。2. 准备工作2.1 注册快递鸟账号首先需要到快递鸟官网注册开发者账号。注册完成后在我的API页面可以找到两个关键参数EBusinessID商户IDAppKeyAPI密钥这两个参数将在后续的API调用中用于身份验证。2.2 了解API文档快递鸟提供了详细的API文档我们需要重点关注以下几个接口即时查询API实时查询物流轨迹订阅API订阅物流状态变更通知识别快递公司API根据单号自动识别快递公司3. 核心代码实现3.1 构建请求参数// 配置参数 $ebusinessId 您的EBusinessID; $appKey 您的AppKey; $reqURL http://api.kdniao.com/Ebusiness/EbusinessOrderHandle.aspx; // 请求数据 $requestData [ OrderCode , // 订单编号(可选) ShipperCode SF, // 快递公司编码 LogisticCode 1234567890, // 快递单号 IsHandleInfo 1 // 是否处理轨迹信息 ];3.2 生成数据签名快递鸟API要求所有请求都必须包含数据签名。签名算法如下function encrypt($data, $appKey) { $data json_encode($data); $data urlencode($data); $sign base64_encode(md5($data.$appKey)); return $sign; } $dataSign encrypt($requestData, $appKey);3.3 发送API请求$postData [ RequestData urlencode(json_encode($requestData)), EBusinessID $ebusinessId, RequestType 1002, // 即时查询API编号 DataSign $dataSign, DataType 2 // 返回数据格式2-JSON ]; // 发送请求 $ch curl_init(); curl_setopt($ch, CURLOPT_URL, $reqURL); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $result curl_exec($ch); curl_close($ch); // 处理返回结果 $result json_decode($result, true);4. 结果处理与展示4.1 解析API返回数据快递鸟API返回的数据结构如下{ Success: true, State: 3, // 物流状态 Traces: [ { AcceptTime: 2023-05-01 10:00:00, AcceptStation: 【北京市】已收件, Remark: }, // 更多轨迹节点... ] }4.2 物流状态码说明快递鸟使用数字表示物流状态0无轨迹1已揽收2在途中3签收4问题件4.3 前端展示实现function formatTraces($traces) { $html div classlogistics-track; foreach($traces as $trace) { $html . div classtrack-item; $html . div classtime.$trace[AcceptTime]./div; $html . div classstation.$trace[AcceptStation]./div; $html . /div; } $html . /div; return $html; } echo formatTraces($result[Traces]);5. 高级功能实现5.1 自动识别快递公司对于不知道快递公司的情况可以使用快递鸟的识别API$requestData [ LogisticCode 1234567890 // 快递单号 ]; $dataSign encrypt($requestData, $appKey); $postData [ RequestData urlencode(json_encode($requestData)), EBusinessID $ebusinessId, RequestType 2002, // 识别API编号 DataSign $dataSign, DataType 2 ]; // 发送请求代码同上...5.2 物流订阅功能对于重要订单可以订阅物流状态变更通知$requestData [ CallBack http://yourdomain.com/callback.php, LogisticCode 1234567890, ShipperCode SF ]; $dataSign encrypt($requestData, $appKey); $postData [ RequestData urlencode(json_encode($requestData)), EBusinessID $ebusinessId, RequestType 1008, // 订阅API编号 DataSign $dataSign, DataType 2 ]; // 发送请求代码同上...6. 性能优化与注意事项6.1 缓存策略频繁查询相同单号会浪费API资源建议实现缓存机制function getLogisticsInfo($logisticCode) { $cacheKey logistics_.$logisticCode; $cacheTime 3600; // 1小时 // 尝试从缓存读取 if($data getFromCache($cacheKey)) { return $data; } // 调用API查询 $data queryFromAPI($logisticCode); // 存入缓存 setToCache($cacheKey, $data, $cacheTime); return $data; }6.2 错误处理API调用可能遇到各种错误需要妥善处理if(!$result[Success]) { // 记录错误日志 error_log(快递鸟API调用失败: .$result[Reason]); // 返回友好提示 return [ error true, message 物流信息查询失败请稍后再试 ]; }6.3 安全性考虑不要在前端暴露AppKey对用户输入的单号进行验证限制API调用频率防止滥用7. 常见问题解决方案7.1 签名验证失败可能原因参数JSON格式不正确AppKey错误未进行URL编码解决方案使用json_encode确保JSON格式正确检查AppKey是否正确确保RequestData经过urlencode处理7.2 返回数据为空可能原因单号错误快递公司编码错误物流信息尚未同步解决方案验证单号是否正确使用识别API确认快递公司稍后再试或联系快递公司7.3 高并发下的性能问题解决方案实现缓存机制使用队列异步处理查询请求考虑购买更高的API套餐8. 完整示例代码class Kdniao { private $ebusinessId; private $appKey; private $apiUrl http://api.kdniao.com/Ebusiness/EbusinessOrderHandle.aspx; public function __construct($ebusinessId, $appKey) { $this-ebusinessId $ebusinessId; $this-appKey $appKey; } private function encrypt($data) { $data json_encode($data); $data urlencode($data); return base64_encode(md5($data.$this-appKey)); } private function sendRequest($requestType, $requestData) { $dataSign $this-encrypt($requestData); $postData [ RequestData urlencode(json_encode($requestData)), EBusinessID $this-ebusinessId, RequestType $requestType, DataSign $dataSign, DataType 2 ]; $ch curl_init(); curl_setopt($ch, CURLOPT_URL, $this-apiUrl); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $result curl_exec($ch); curl_close($ch); return json_decode($result, true); } public function queryLogistics($shipperCode, $logisticCode) { $requestData [ OrderCode , ShipperCode $shipperCode, LogisticCode $logisticCode, IsHandleInfo 1 ]; return $this-sendRequest(1002, $requestData); } public function identifyLogistics($logisticCode) { $requestData [ LogisticCode $logisticCode ]; return $this-sendRequest(2002, $requestData); } public function subscribeLogistics($shipperCode, $logisticCode, $callbackUrl) { $requestData [ CallBack $callbackUrl, LogisticCode $logisticCode, ShipperCode $shipperCode ]; return $this-sendRequest(1008, $requestData); } } // 使用示例 $kdniao new Kdniao(您的EBusinessID, 您的AppKey); $result $kdniao-queryLogistics(SF, 1234567890); print_r($result);在实际项目中这个类可以进一步封装到你的框架中或者作为一个独立的服务组件使用。根据我的经验这种封装方式既保持了灵活性又能很好地复用代码。 
长河君 · 2026/10/26 11:07:33 · 阅读 1.2k PHP对接快递鸟物流API实现实时轨迹查询
1. 项目概述最近在开发一个电商后台系统时遇到了需要实时查询物流信息的需求。经过多方对比最终选择了快递鸟的物流轨迹查询API作为解决方案。这个方案最大的优势在于支持国内主流快递公司的单号查询而且响应速度快、稳定性好。快递鸟API提供了完整的物流轨迹查询功能包括在途监控、电子面单、轨迹推送等服务。我们主要使用其在途监控功能通过单号就能获取完整的物流流转信息。下面我将详细介绍如何在PHP项目中对接这个API。2. 准备工作2.1 注册快递鸟账号首先需要到快递鸟官网注册开发者账号。注册完成后在我的API页面可以找到两个关键参数EBusinessID商户IDAppKeyAPI密钥这两个参数将在后续的API调用中用于身份验证。2.2 了解API文档快递鸟提供了详细的API文档我们需要重点关注以下几个接口即时查询API实时查询物流轨迹订阅API订阅物流状态变更通知识别快递公司API根据单号自动识别快递公司3. 核心代码实现3.1 构建请求参数// 配置参数 $ebusinessId 您的EBusinessID; $appKey 您的AppKey; $reqURL http://api.kdniao.com/Ebusiness/EbusinessOrderHandle.aspx; // 请求数据 $requestData [ OrderCode , // 订单编号(可选) ShipperCode SF, // 快递公司编码 LogisticCode 1234567890, // 快递单号 IsHandleInfo 1 // 是否处理轨迹信息 ];3.2 生成数据签名快递鸟API要求所有请求都必须包含数据签名。签名算法如下function encrypt($data, $appKey) { $data json_encode($data); $data urlencode($data); $sign base64_encode(md5($data.$appKey)); return $sign; } $dataSign encrypt($requestData, $appKey);3.3 发送API请求$postData [ RequestData urlencode(json_encode($requestData)), EBusinessID $ebusinessId, RequestType 1002, // 即时查询API编号 DataSign $dataSign, DataType 2 // 返回数据格式2-JSON ]; // 发送请求 $ch curl_init(); curl_setopt($ch, CURLOPT_URL, $reqURL); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $result curl_exec($ch); curl_close($ch); // 处理返回结果 $result json_decode($result, true);4. 结果处理与展示4.1 解析API返回数据快递鸟API返回的数据结构如下{ Success: true, State: 3, // 物流状态 Traces: [ { AcceptTime: 2023-05-01 10:00:00, AcceptStation: 【北京市】已收件, Remark: }, // 更多轨迹节点... ] }4.2 物流状态码说明快递鸟使用数字表示物流状态0无轨迹1已揽收2在途中3签收4问题件4.3 前端展示实现function formatTraces($traces) { $html div classlogistics-track; foreach($traces as $trace) { $html . div classtrack-item; $html . div classtime.$trace[AcceptTime]./div; $html . div classstation.$trace[AcceptStation]./div; $html . /div; } $html . /div; return $html; } echo formatTraces($result[Traces]);5. 高级功能实现5.1 自动识别快递公司对于不知道快递公司的情况可以使用快递鸟的识别API$requestData [ LogisticCode 1234567890 // 快递单号 ]; $dataSign encrypt($requestData, $appKey); $postData [ RequestData urlencode(json_encode($requestData)), EBusinessID $ebusinessId, RequestType 2002, // 识别API编号 DataSign $dataSign, DataType 2 ]; // 发送请求代码同上...5.2 物流订阅功能对于重要订单可以订阅物流状态变更通知$requestData [ CallBack http://yourdomain.com/callback.php, LogisticCode 1234567890, ShipperCode SF ]; $dataSign encrypt($requestData, $appKey); $postData [ RequestData urlencode(json_encode($requestData)), EBusinessID $ebusinessId, RequestType 1008, // 订阅API编号 DataSign $dataSign, DataType 2 ]; // 发送请求代码同上...6. 性能优化与注意事项6.1 缓存策略频繁查询相同单号会浪费API资源建议实现缓存机制function getLogisticsInfo($logisticCode) { $cacheKey logistics_.$logisticCode; $cacheTime 3600; // 1小时 // 尝试从缓存读取 if($data getFromCache($cacheKey)) { return $data; } // 调用API查询 $data queryFromAPI($logisticCode); // 存入缓存 setToCache($cacheKey, $data, $cacheTime); return $data; }6.2 错误处理API调用可能遇到各种错误需要妥善处理if(!$result[Success]) { // 记录错误日志 error_log(快递鸟API调用失败: .$result[Reason]); // 返回友好提示 return [ error true, message 物流信息查询失败请稍后再试 ]; }6.3 安全性考虑不要在前端暴露AppKey对用户输入的单号进行验证限制API调用频率防止滥用7. 常见问题解决方案7.1 签名验证失败可能原因参数JSON格式不正确AppKey错误未进行URL编码解决方案使用json_encode确保JSON格式正确检查AppKey是否正确确保RequestData经过urlencode处理7.2 返回数据为空可能原因单号错误快递公司编码错误物流信息尚未同步解决方案验证单号是否正确使用识别API确认快递公司稍后再试或联系快递公司7.3 高并发下的性能问题解决方案实现缓存机制使用队列异步处理查询请求考虑购买更高的API套餐8. 完整示例代码class Kdniao { private $ebusinessId; private $appKey; private $apiUrl http://api.kdniao.com/Ebusiness/EbusinessOrderHandle.aspx; public function __construct($ebusinessId, $appKey) { $this-ebusinessId $ebusinessId; $this-appKey $appKey; } private function encrypt($data) { $data json_encode($data); $data urlencode($data); return base64_encode(md5($data.$this-appKey)); } private function sendRequest($requestType, $requestData) { $dataSign $this-encrypt($requestData); $postData [ RequestData urlencode(json_encode($requestData)), EBusinessID $this-ebusinessId, RequestType $requestType, DataSign $dataSign, DataType 2 ]; $ch curl_init(); curl_setopt($ch, CURLOPT_URL, $this-apiUrl); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $result curl_exec($ch); curl_close($ch); return json_decode($result, true); } public function queryLogistics($shipperCode, $logisticCode) { $requestData [ OrderCode , ShipperCode $shipperCode, LogisticCode $logisticCode, IsHandleInfo 1 ]; return $this-sendRequest(1002, $requestData); } public function identifyLogistics($logisticCode) { $requestData [ LogisticCode $logisticCode ]; return $this-sendRequest(2002, $requestData); } public function subscribeLogistics($shipperCode, $logisticCode, $callbackUrl) { $requestData [ CallBack $callbackUrl, LogisticCode $logisticCode, ShipperCode $shipperCode ]; return $this-sendRequest(1008, $requestData); } } // 使用示例 $kdniao new Kdniao(您的EBusinessID, 您的AppKey); $result $kdniao-queryLogistics(SF, 1234567890); print_r($result);在实际项目中这个类可以进一步封装到你的框架中或者作为一个独立的服务组件使用。根据我的经验这种封装方式既保持了灵活性又能很好地复用代码。