顺丰PHP下单API如何调用与配置？

99ANYc3cd6 顺丰快递 2026-01-26 2

我会为你提供一个完整的、分步的指南，包括：

（图片来源网络，侵删）

准备工作：获取必要的密钥和文档。
核心概念：理解顺丰API的认证和数据格式。
PHP实现步骤：分步讲解如何构建请求、发送请求并处理响应。
完整代码示例：提供一个可以直接运行的PHP脚本。
注意事项和常见问题。

准备工作

在开始编码之前,你必须完成以下准备工作：

申请顺丰开发者账号：
- 访问顺丰开放平台官网：https://open.sf-express.com/
- 注册并登录开发者账号。
创建应用，获取密钥：
- 在开发者后台,创建一个新的应用。
- 创建成功后,系统会为你分配两对关键的密钥：
  - 客户编码：你的企业标识。
  - checkword (或称授权码/秘钥)：用于生成签名的密钥，请务必妥善保管，不要泄露。
阅读官方API文档：
（图片来源网络，侵删）
- 这是最重要的一步，顺丰的API会不断更新，最新的逻辑和参数都在官方文档中。
- 在顺丰开放平台找到“API服务”或“开发者文档”，找到与下单相关的接口，通常是 orderService 或类似的名称。
- 仔细阅读文档中的接口说明、请求参数、返回码、数据字典和接入指南，我们这里的代码是基于通用逻辑，具体细节请以官方文档为准。

核心概念

顺丰API的调用主要涉及三个核心点：

a. 签名认证

为了保证接口调用的安全性,顺丰要求每个请求都必须包含一个签名，签名是通过对请求参数和你的密钥进行特定算法（通常是MD5或SHA1）计算得出的。

签名生成的一般流程（请以官方文档为准）：

收集参数：将所有请求参数（不包括文件）按照参数名的ASCII码从小到大排序（字典序）。
拼接字符串：将排序后的参数名和参数值使用key=value的格式拼接，并在这些拼接字符串之间使用&符号连接。
追加密钥：在上一步拼接得到的字符串末尾，追加你的checkword（授权码）。
计算签名：对最终得到的字符串进行MD5（或SHA1）加密，得到的32位（或40位）小写字符串就是最终的签名值。

参数：paramA=1&paramB=2&paramC=3
排序后：paramA=1&paramB=2&paramC=3 (假设顺序不变)
追加密钥：paramA=1&paramB=2&paramC=3&YOUR_CHECKWORD
MD5后得到的字符串就是签名。

b. XML数据格式

顺丰API的请求和响应都使用XML格式,而不是更常见的JSON，你需要构建一个符合其规范的XML字符串作为请求体。

（图片来源网络，侵删）

一个典型的下单请求XML结构大致如下：

<?xml version="1.0" encoding="utf-8"?>
<Request>
    <Head>
        <PartnerID>你的客户编码</PartnerID>
        <PartnerKey>你的授权码</PartnerKey>
        <!-- 其他头部信息，如时间戳等 -->
    </Head>
    <Body>
        <!-- 这里是具体的下单信息，如收寄件人信息、物品信息等 -->
        <Order>
            <OrderCode>YOUR_ORDER_ID_001</OrderCode>
            <PayMethod>1</PayMethod>
            <TotalFreight>22.00</TotalFreight>
            <Sender>
                <Name>张三</Name>
                <Phone>13800138000</Phone>
                <Province>广东省</Province>
                <City>深圳市</City>
                <Address>南山区科技园</Address>
            </Sender>
            <Receiver>
                <Name>李四</Name>
                <Phone>13900139000</Phone>
                <Province>北京市</Province>
                <City>北京市</City>
                <Address>朝阳区望京</Address>
            </Receiver>
            <!-- 更多订单详情... -->
        </Order>
    </Body>
</Request>

c. HTTPS 通信

所有API请求都必须通过HTTPS协议发送,以确保数据传输过程中的加密和安全。

PHP实现步骤

我们将使用PHP的cURL库来发送HTTPS请求。

步骤1：构建请求参数和签名

// 1. 准备基础参数
$params = [
    'partner_id' => 'YOUR_PARTNER_ID', // 你的客户编码
    'request_time' => date('Y-m-d H:i:s'), // 请求时间，格式通常为 Y-m-d H:i:s
    // ... 其他公共参数
];
// 2. 对参数进行排序
ksort($params);
// 3. 拼接成 key=value&key=value... 的格式
$stringToSign = '';
foreach ($params as $key => $value) {
    $stringToSign .= $key . '=' . $value . '&';
}
// 去掉最后一个多余的 '&'
$stringToSign = rtrim($stringToSign, '&');
// 4. 追加授权码 (checkword)
$checkword = 'YOUR_CHECKWORD'; // 你的授权码
$stringToSign .= $checkword;
// 5. 计算MD5签名
$signature = md5($stringToSign);
// 6. 将签名添加到参数数组中
$params['signature'] = $signature;

步骤2：构建XML请求体

根据顺丰的文档,将订单信息组装成一个XML字符串，这里可以使用字符串拼接，但对于复杂的XML，推荐使用PHP内置的SimpleXMLElement或DOMDocument类来构建，以避免格式错误。

// 使用 SimpleXMLElement 构建 XML
$xml = new SimpleXMLElement('<Request></Request>');
$head = $xml->addChild('Head');
$head->addChild('PartnerID', 'YOUR_PARTNER_ID');
$head->addChild('PartnerKey', 'YOUR_CHECKWORD');
$head->addChild('RequestTime', date('Y-m-d H:i:s'));
$body = $xml->addChild('Body');
$order = $body->addChild('Order');
$order->addChild('OrderCode', 'PHP_ORDER_' . time());
$order->addChild('PayMethod', '1');
$sender = $order->addChild('Sender');
$sender->addChild('Name', '张三');
$sender->addChild('Phone', '13800138000');
// ... 添加更多收寄件人信息
// 将 SimpleXMLElement 对象转换为字符串
$requestXml = $xml->asXML();
// 为了确保格式正确，可以保存到文件检查一下
// file_put_contents('request.xml', $requestXml);

步骤3：使用cURL发送请求

// 顺丰API的请求地址，请从官方文档获取
$url = 'https://open.sf-express.com/api/service'; // 这只是一个示例地址，请替换为真实的
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestXml);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); // 验证证书
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);     // 检查证书主域名是否一致
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: text/xml; charset=utf-8',
    'Content-Length: ' . strlen($requestXml)
]);
$response = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'cURL Error: ' . curl_error($ch);
} else {
    // 4. 处理响应
    $responseXml = simplexml_load_string($response);
    if ($responseXml === false) {
        echo "Failed to parse XML response.";
        echo "\nResponse: " . $response;
    } else {
        // 检查业务是否成功
        // 顺丰通常会在Response的Head或Body里有一个表示成功/失败的字段，如 'ResultCode', 'ServiceCode' 等
        // 请务必根据官方文档来解析返回结果
        $resultCode = (string)$responseXml->Head->ResultCode;
        if ($resultCode == '0' || $resultCode == '200') { // 成功码请以文档为准
            echo "下单成功！";
            echo "\n运单号: " . (string)$responseXml->Body->Order->MailNo;
        } else {
            $errorMsg = (string)$responseXml->Head->ErrorMessage;
            echo "下单失败！错误码: " . $resultCode . ", 错误信息: " . $errorMsg;
        }
    }
}
curl_close($ch);

完整代码示例

这是一个整合了上述步骤的完整示例。请务必根据你的实际情况和官方文档修改参数和XML结构。

<?php
/**
 * 顺丰PHP下单API调用示例
 */
// ========================================
// 1. 配置信息 - 请替换为你自己的信息
// ========================================
$config = [
    'partner_id'    => 'YOUR_PARTNER_ID',       // 客户编码
    'checkword'     => 'YOUR_CHECKWORD',        // 授权码
    'api_url'       => 'https://open.sf-express.com/api/orderService', // 官方提供的下单API地址
];
// ========================================
// 2. 构建请求XML
// ========================================
try {
    $xml = new SimpleXMLElement('<Request></Request>');
    $head = $xml->addChild('Head');
    $head->addChild('PartnerID', $config['partner_id']);
    $head->addChild('PartnerKey', $config['checkword']);
    $head->addChild('RequestTime', date('Y-m-d H:i:s'));
    $body = $xml->addChild('Body');
    $order = $body->addChild('Order');
    // --- 订单信息 ---
    $order->addChild('OrderCode', 'PHP_SF_ORDER_' . uniqid()); // 唯一订单号
    $order->addChild('PayMethod', '1'); // 1:寄付月结, 2:寄付现结, 3:到付
    $order->addChild('TotalFreight', '22.00');
    $order->addChild('Remark', 'PHP API测试订单');
    // --- 寄件人信息 ---
    $sender = $order->addChild('Sender');
    $sender->addChild('Name', '张三');
    $sender->addChild('Phone', '13800138000');
    $sender->addChild('Province', '广东省');
    $sender->addChild('City', '深圳市');
    $sender->addChild('County', '南山区');
    $sender->addChild('Address', '科技园路1号');
    // --- 收件人信息 ---
    $receiver = $order->addChild('Receiver');
    $receiver->addChild('Name', '李四');
    $receiver->addChild('Phone', '13900139000');
    $receiver->addChild('Province', '北京市');
    $receiver->addChild('City', '北京市');
    $receiver->addChild('County', '朝阳区');
    $receiver->addChild('Address', '望京SOHO T1');
    // --- 物品信息 ---
    $item = $order->addChild('Item');
    $item->addChild('Name', '文件');
    $item->addChild('Quantity', '1');
    $item->addChild('Weight', '0.5'); // 单位：公斤
    $requestXml = $xml->asXML();
    // (可选) 将请求XML保存到文件，方便调试
    // file_put_contents('sf_request.xml', $requestXml);
} catch (Exception $e) {
    die('构建XML失败: ' . $e->getMessage());
}
// ========================================
// 3. 发送cURL请求
// ========================================
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $config['api_url']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestXml);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: text/xml; charset=utf-8',
    'Content-Length: ' . strlen($requestXml)
]);
$response = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'cURL Error: ' . curl_error($ch);
    curl_close($ch);
    exit;
}
curl_close($ch);
// ========================================
// 4. 处理响应
// ========================================
echo "===== 顺丰API响应 =====\n";
echo $response . "\n\n";
try {
    $responseXml = simplexml_load_string($response);
    if ($responseXml === false) {
        echo "解析XML响应失败，\n";
    } else {
        // 根据官方文档解析返回结果
        // 通常ResultCode为0或200表示成功
        $resultCode = (string)$responseXml->Head->ResultCode;
        $errorMsg = (string)$responseXml->Head->ErrorMessage;
        if ($resultCode == '0' || $resultCode == '200') {
            echo "【下单成功】\n";
            // 获取运单号
            $mailNo = (string)$responseXml->Body->Order->MailNo;
            echo "运单号: " . $mailNo . "\n";
        } else {
            echo "【下单失败】\n";
            echo "错误码: " . $resultCode . "\n";
            echo "错误信息: " . $errorMsg . "\n";
        }
    }
} catch (Exception $e) {
    echo '处理响应时发生异常: ' . $e->getMessage();
}
?>

注意事项和常见问题

官方文档是第一准则：再次强调，所有代码逻辑（如参数名、XML结构、签名算法、成功/失败判断码）都必须以顺丰官方最新文档为准，此示例仅提供通用流程。
沙箱环境：顺丰通常提供沙箱环境供开发者测试。请务必先在沙箱环境完成开发和测试，确认无误后再切换到生产环境，沙箱环境的API地址和密钥通常与生产环境不同。
字符编码：确保你的PHP文件、XML数据和HTTP请求头都使用UTF-8编码，这是避免乱码的关键。
参数必填性：仔细检查文档，确保所有必填参数都已填写，否则会返回参数错误。
签名错误：如果返回1001（签名错误）之类的码，请仔细检查你的签名生成逻辑，特别是参数排序和追加密钥的步骤。
超时和重试：网络请求可能失败，建议在你的业务逻辑中加入超时设置和失败重试机制。
错误码对照：将顺丰官方文档中的所有错误码整理成一个对照表，方便排查问题。
物流轨迹查询：下单成功后，你可以使用返回的运单号MailNo，再调用顺丰的物流轨迹查询API来获取包裹的最新状态，这个API的调用流程与下单类似，但请求参数和XML结构不同。

标签：顺丰PHP下单API调用教程顺丰快递API配置PHP代码示例 PHP对接顺丰下单API完整流程

本文地址： https://www.sxsfhsy.com/post/7617.html