如何正确调用快递100实时物流API（PHP POST请求与签名验证）-php教程-PHP中文网

如何正确调用快递100实时物流API（PHP POST请求与签名验证）

本文详解快递100（kd100）实时物流api的php调用方法，重点解决因签名（signature）生成错误导致的“invalid signature”（错误码104）问题，涵盖参数构造、md5签名规范、http头设置及curl完整实现。

本文详解快递100（kd100）实时物流api的php调用方法，重点解决因签名（signature）生成错误导致的“invalid signature”（错误码104）问题，涵盖参数构造、md5签名规范、http头设置及curl完整实现。

快递100（KD100）实时物流API要求严格校验请求签名，签名错误是返回 {"code":104,"message":"Invalid signature"} 的最常见原因。核心问题在于：签名字符串必须为大写MD5哈希值，且参与签名的原始数据顺序、编码方式必须与文档完全一致。

根据官方文档，签名规则如下：
signature = strtoupper(md5(param + API-Key + SecretKey))
其中：

param 是 JSON 字符串（非数组），需使用 JSON_UNESCAPED_UNICODE 保证中文不转义；
API-Key 与 SecretKey 为平台分配的凭证，区分大小写；
所有拼接无分隔符，顺序不可颠倒。

以下是修正后的完整、可运行的 PHP 示例代码：

PHP

编写健壮的PHP代码，规避类型转换陷阱、数组怪癖及常见安全漏洞。

下载

<?php $key = 'YOUR_API_KEY';           // 替换为你的API Key
$secret = 'YOUR_SECRET_KEY';     // 替换为你的Secret Key
$param = [
    'carrier_id' => 'usps',
    'tracking_number' => '9400110898825456789012' // 替换为真实单号
];

// 1. 构造JSON字符串（关键：必须是字符串，且保留Unicode）
$paramJson = json_encode($param, JSON_UNESCAPED_UNICODE);

// 2. 生成签名：按顺序拼接 param + key + secret，再MD5并转大写
$sign = strtoupper(md5($paramJson . $key . $secret));

// 3. 准备POST数据：param字段值为上述JSON字符串
$postData = [
    'param' => $paramJson
];

// 4. 初始化cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.kd100.com/api/v1/tracking/realtime');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 生产环境建议设为true并配置CA证书
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);

// 5. 设置HTTP Header（注意：signature和API-Key必须为大写，且字段名首字母大写）
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/x-www-form-urlencoded',
    'API-Key: ' . $key,
    'signature: ' . $sign  // 注意：此处变量必须是已转大写的$sign
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// 6. 解析响应
$result = json_decode($response, true);
if ($result === null && json_last_error() !== JSON_ERROR_NONE) {
    echo "JSON解析失败：", json_last_error_msg(), "\n";
} else {
    echo "HTTP状态码：", $httpCode, "\n";
    print_r($result);
}
?>

⚠️ 关键注意事项：

签名大小写敏感：strtoupper(md5(...)) 缺一不可，直接使用 md5() 返回小写会导致验证失败；
Header字段命名规范：文档要求 API-Key 和 signature 首字母大写（即 API-Key，非 api-key 或 apikey）；
Content-Type匹配：因使用 http_build_query() 发送表单数据，Header中应为 application/x-www-form-urlencoded，而非 application/json；
避免冗余变量：原代码中 $header_data 数组未被实际使用，应删除以提升可读性；
生产安全建议：禁用 CURLOPT_SSL_VERIFYPEER 和 CURLOPT_SSL_VERIFYHOST 仅适用于调试，上线前务必启用SSL证书验证。

通过以上修正，即可稳定调用快递100实时物流接口，成功获取物流轨迹数据。建议将签名逻辑封装为独立函数，并增加异常捕获与日志记录，便于后续维护与问题排查。