本文详解php中调用快递100（kd100）实时物流api时出现“invalid signature（错误码104）”的根源与修复方案，重点纠正签名生成逻辑、http头设置及curl配置中的常见错误。
本文详解php中调用快递100（kd100）实时物流api时出现“invalid signature（错误码104）”的根源与修复方案，重点纠正签名生成逻辑、http头设置及curl配置中的常见错误。
在使用快递100（KD100）实时物流追踪API（https://www.php.cn/link/cbc2dfc663cb73ab445ac5f735efb92b）时，开发者常因签名（signature）校验失败而收到 {"code":104,"message":"Invalid signature"} 响应。该错误并非密钥错误或网络问题，而是签名生成与请求头传递不一致所致——核心问题在于：签名值未统一为大写，且构造后未被正确注入请求头。
? 签名规则回顾（关键！）
根据官方文档，signature 必须按以下顺序拼接并进行 MD5哈希 + 全大写转换：
md5( json字符串 + API-Key + SecretKey ) → 转为大写十六进制
注意：json字符串 是原始 param 数组经 json_encode(..., JSON_UNESCAPED_UNICODE) 生成的不含空格、无换行的紧凑JSON；且整个拼接过程不可添加额外空格或分隔符。
✅ 正确实现（已修复所有关键问题）
<?php
$key = 'YOUR_API_KEY'; // 替换为实际API Key
$secret = 'YOUR_SECRET_KEY'; // 替换为实际Secret Key
$param = [
'carrier_id' => 'usps',
'tracking_number'=> '9400111899999999999999' // 示例USPS单号
];
// 1. 生成紧凑JSON（关键：无空格、UTF-8原生编码）
$jsonParam = json_encode($param, JSON_UNESCAPED_UNICODE);
// 2. 严格按文档拼接并生成大写签名（⚠️ 一步到位，避免中间变量歧义）
$sign = strtoupper(md5($jsonParam . $key . $secret));
// 3. 构建POST数据体：param字段必须是JSON字符串（非数组！）
$postData = [
'param' => $jsonParam // 注意：不是 json_encode($param) 再套一层！
];
// 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_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 生产环境请启用证书验证
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData)); // 发送表单格式
// 5. 设置HTTP Header（✅ 使用 $sign，非 $header_data['signature']）
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/x-www-form-urlencoded', // ⚠️ 非 application/json！
'API-Key: ' . $key,
'signature: ' . $sign // ✅ 直接传入已转大写的 $sign
]);
// 6. 执行请求并解析
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($response === false) {
die('cURL Error: ' . curl_error($ch));
}
$result = json_decode($response, true);
echo "<pre>";
print_r($result);
echo "</pre>";
?>⚠️ 关键注意事项（避坑清单）
Content-Type 必须为 application/x-www-form-urlencoded
尽管 param 是JSON字符串，但API要求以表单方式提交（http_build_query），而非原始JSON Body。若设为 application/json 并直接发送JSON对象，将导致签名无效或400错误。-
签名必须全程大写
md5() 返回小写十六进制字符串，strtoupper() 不可省略。错误示例：$sign = md5(...); 后未转大写即用于Header。立即学习“PHP免费学习笔记（深入）”；
不要定义无用的 $header_data 数组
原代码中 $header_data['signature'] = strtoupper($sign) 定义了却未使用，反而在 CURLOPT_HTTPHEADER 中错误地传入了未转大写的 $sign 变量——这是引发104错误的直接原因。生产环境务必启用SSL验证
CURLOPT_SSL_VERIFYPEER 和 CURLOPT_SSL_VERIFYHOST 应设为 true，并配置CA证书路径（如 curl_setopt($ch, CURLOPT_CAINFO, '/path/to/cacert.pem');）。-
调试建议
在发送前打印签名和拼接串用于比对：echo "Debug sign string: '" . $jsonParam . $key . $secret . "'\n"; echo "Generated sign: " . $sign . "\n";
遵循以上规范，即可稳定调用KD100实时物流API。签名机制是第三方API安全接入的核心环节，细微的大小写、空格、编码差异均会导致验证失败——严谨对待每一步，是API集成成功的关键。
