PHP物流查询API如何对接与使用？

99ANYc3cd6 11-28 1

默认

摘要： 什么是物流查询 API？物流查询 API（Application Programming Interface）是一种服务接口，允许开发者通过 HTTP 请求，将运单号（快递单号）发...

什么是物流查询 API？

物流查询 API（Application Programming Interface）是一种服务接口，允许开发者通过 HTTP 请求，将运单号（快递单号）发送给物流服务商的服务器，然后获取该运单号的最新物流轨迹、状态、签收信息等数据。

（图片来源网络，侵删）

对于 PHP 这意味着你可以在自己的网站、App 或后台系统中，无缝集成物流查询功能，而无需自己去对接各家快递公司的系统。

主流的物流查询 API 服务商

选择合适的 API 服务商是关键，主要分为两类：聚合平台和官方直连。

聚合平台 (推荐)

这类平台与多家快递公司合作,你只需要对接一个 API，就能查询成百上千家快递公司的物流信息，它们是中小型项目的首选。

快递鸟
（图片来源网络，侵删）
- 特点：国内最知名的物流查询 API 服务商之一，支持快递公司数量多，文档清晰，有免费测试额度。
- 官网：https://www.kdniao.com/
- 计费：通常按查询次数收费，有不同套餐。
快递100
- 特点：用户量巨大，产品线丰富（查询、打印、电子面单等），API 稳定可靠。
- 官网：https://www.kuaidi100.com/
- 计费：同样按查询次数收费，提供免费试用。
聚合数据
- 特点：除了物流查询，还提供多种其他数据服务，API 种类齐全。
- 官网：https://www.juhe.cn/
- 计费：按调用量收费。

聚合平台的优势：

一站式服务：对接一次，查询所有。
数据覆盖广：几乎没有查不到的快递。
技术维护简单：由平台负责维护与各快递公司的对接，你只需调用 API。

官方直连

直接对接快递公司（如顺丰、京东、三通一达等）的官方 API。

（图片来源网络，侵删）

顺丰速运
- 特点：数据最权威、最及时，但 API 申请流程相对复杂，需要企业资质，接口文档较复杂。
- 官网：https://www.sf-express.com/ (需在“客户开发”中寻找 API 入口)
京东物流
- 特点：同样数据质量高，但主要面向京东生态内的合作伙伴或大客户，开放程度不如聚合平台。

官方直连的优势：

数据直接：一手数据，无中间环节。
可能免费：部分官方 API 对其大客户可能免费。

劣势：

对接成本高：需要为每家快递单独申请、开发、维护，工作量大。
覆盖不全：无法覆盖所有小众快递公司。

如何选择？

场景	推荐选择	原因
中小型网站、电商系统、个人项目	聚合平台 (如快递鸟、快递100)	开发快、成本低、覆盖全、无需维护多家快递接口。
大型企业、对数据实时性要求极高	官方直连 (如顺丰) + 聚合平台	核心快递（如顺丰）用官方直连保证数据权威，其他用聚合平台补充。
已有系统，只需增加查询功能	聚合平台	最小化改动，快速上线。

PHP 代码示例 (以快递鸟为例)

下面我将演示如何使用 PHP 调用快递鸟的 API 进行物流查询，其他平台的流程基本类似，只需修改请求地址和参数格式。

第 1 步：准备工作

注册账号：在快递鸟官网注册并登录。
获取 API 信息：在后台获取你的 EBusinessID (电商ID) 和 AppKey (API key)。
查看文档：下载最新的 API 接口文档，了解请求格式、参数和返回数据结构。

第 2 步：编写 PHP 代码

快递鸟的查询接口通常使用 POST 请求，并且请求体是 JSON 格式，你需要使用 PHP 的 cURL 扩展来发送请求。

<?php
/**
 * 物流查询API - 快递鸟示例
 */
// 1. 配置信息 (请替换为你自己的信息)
$config = [
    'EBusinessID' => '你的电商ID',
    'AppKey'      => '你的AppKey',
    'ReqURL'      => 'https://api.kdniao.com/api/dist', // 快递鸟查询接口地址
];
// 2. 准备请求数据
$requestData = [
    'Com' => 'YTO',         // 快递公司编码 (YTO: 顺丰, ZTO: 中通, STO: 申通等)
    'Num' => 'SF1234567890', // 快递单号
];
// 3. 调用API并获取结果
$result = queryLogistics($config, $requestData);
// 4. 输出结果
echo "<pre>";
print_r($result);
echo "</pre>";
/**
 * 调用快递鸟物流查询API
 * @param array $config 配置信息
 * @param array $requestData 请求参数
 * @return string JSON格式的响应结果
 */
function queryLogistics($config, $requestData)
{
    // 生成电子面单请求参数
    $requestData['schema'] = 'json'; // 指定返回数据格式为JSON
    // 请求参数按字母排序
    ksort($requestData);
    // 拼接签名字符串
    $signStr = '';
    foreach ($requestData as $key => $value) {
        $signStr .= $key . $value;
    }
    $signStr .= $config['AppKey']; // AppKey拼接到最后
    // 生成MD5签名 (注意：API文档中可能要求转大写或做其他处理，请以最新文档为准)
    $sign = strtoupper(md5($signStr));
    // 构建最终请求的JSON数据
    $postJsonData = json_encode([
        'RequestData' => urlencode(json_encode($requestData)), // RequestData需要URL编码
        'EBusinessID' => $config['EBusinessID'],
        'RequestType' => '1002', // 1002表示即时查询
        'DataSign'    => $sign,
        'DataType'    => '2', // 2代表JSON
    ]);
    // 初始化cURL
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $config['ReqURL']);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 跳过证书检查 (生产环境建议开启)
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); // 跳过主机检查 (生产环境建议开启)
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $postJsonData);
    // 执行请求
    $result = curl_exec($ch);
    // 关闭cURL
    curl_close($ch);
    return $result;
}
?>

代码解释

配置信息：将你的 EBusinessID 和 AppKey 填入 $config 数组。
请求数据：$requestData 中，Com 是快递公司编码，Num 是运单号，这些编码通常可以在服务商的文档中找到。
签名生成：这是 API 调用的核心和难点，服务商为了保证请求的安全性，要求你按照特定规则（通常是参数按字母排序后拼接，再加上密钥）生成一个签名。请务必以服务商官方最新文档中的签名规则为准。
cURL 请求：
- 使用 POST 方式将 JSON 数据发送到 API 地址。
- RequestData 字段本身是一个 JSON 字符串，根据文档要求，它需要先 json_encode，然后再用 urlencode 进行编码。
- DataSign 就是上一步生成的签名。
- CURLOPT_SSL_VERIFYPEER 和 CURLOPT_SSL_VERIFYHOST 在开发环境可以设为 false 以避免证书问题，但在生产环境中强烈建议开启以保证安全。
处理结果：curl_exec() 返回的是服务商返回的 JSON 字符