在电商、仓储类PHP项目中，实现订单物流信息查询是常见需求，对接第三方物流API可以避免手动维护物流公司接口，降低开发成本。本文以快递100的物流查询接口为例，讲解PHP调用第三方物流API查询订单的完整实现方法。
一、前期准备工作
首先需要在快递100官网注册账号，进入控制台申请物流查询接口，获取专属的key和customer参数，这两个参数是后续请求接口的身份凭证。同时需要确认接口的请求地址、支持的快递公司编码规则，避免后续请求出现参数错误。
二、核心请求逻辑实现
快递100的物流查询接口采用POST请求方式，需要按照指定规则生成签名参数，再将所有参数拼接后发送请求。签名生成规则是将key、快递公司编码、物流单号、customer拼接后进行MD5加密，再转为大写。
以下是完整的PHP实现代码：
<?php
/**
* PHP调用快递100API查询物流订单
* @param string $com 快递公司编码，比如yunda代表韵达
* @param string $num 物流单号
* @return array 物流查询结果
*/
function queryLogistics($com, $num) {
// 接口配置参数，替换为自己的实际参数
$key = 'your_api_key';
$customer = 'your_customer_id';
$apiUrl = 'https://poll.kuaidi100.com/poll/query.do';
// 生成签名
$signStr = $key . $com . $num . $customer;
$sign = strtoupper(md5($signStr));
// 构造请求参数
$param = [
'com' => $com,
'num' => $num,
'from' => '',
'to' => '',
'resultv2' => '1'
];
$postData = [
'customer' => $customer,
'sign' => $sign,
'param' => json_encode($param)
];
// 发送POST请求
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
$response = curl_exec($ch);
$error = curl_error($ch);
curl_close($ch);
// 处理请求结果
if ($error) {
return ['code' => -1, 'msg' => '请求失败：' . $error];
}
$result = json_decode($response, true);
if ($result['status'] == '200') {
return ['code' => 0, 'msg' => '查询成功', 'data' => $result['data']];
} else {
return ['code' => -1, 'msg' => '查询失败：' . $result['message']];
}
}
// 调用示例，查询韵达快递单号123456789的物流信息
$res = queryLogistics('yunda', '123456789');
print_r($res);
?>三、结果解析与异常处理
接口返回的成功结果中，data字段包含物流轨迹列表，每个轨迹项包含时间、状态描述等信息，可以直接遍历展示给用户。需要注意处理几种常见异常情况：
- 物流单号错误或者对应快递公司编码不匹配，接口会返回错误信息，需要提示用户核对信息
- 请求频率超过接口限制，需要添加请求间隔或者缓存机制，避免被接口封禁
- 网络请求失败，需要添加重试逻辑，提升功能稳定性
四、优化建议
实际项目中可以对查询结果做缓存处理，相同单号短时间内不需要重复请求接口，减少接口调用成本。同时可以将快递公司编码和名称的映射关系维护在配置文件中，方便用户选择快递公司时自动匹配对应编码，降低使用门槛。
如果对接其他第三方物流API，整体流程类似，只需要替换对应的接口地址、参数规则、签名生成方式即可，核心的curl请求和结果处理逻辑可以复用。