簽名生成Python示例：

import hashlib

import urllib.parse

import json



def generate_sto_sign(params, secret_key):

    # 1. 過濾系統參數（如sign, method等）和空值參數

    filtered_params = {k: v for k, v in params.items() if v is not None and v != '' and not k.startswith('stc_')}

    # 2. 按參數名ASCII碼升序排序

    sorted_keys = sorted(filtered_params.keys())

    # 3. 拼接鍵值對

    query_string = ''

    for key in sorted_keys:

        value = str(filtered_params[key])

        # 關鍵：對鍵和值進行URL編碼（注意申通通常要求使用RFC 3986編碼）

        encoded_key = urllib.parse.quote(key, safe='')

        encoded_value = urllib.parse.quote(value, safe='')

        query_string += f"{encoded_key}{encoded_value}"

    # 4. 拼接密鑰

    sign_string = secret_key + query_string + secret_key

    # 5. MD5計算并轉為大寫

    md5 = hashlib.md5()

    md5.update(sign_string.encode('utf-8'))

    return md5.hexdigest().upper()



# 示例參數

params = {

    "method": "stc.order.waybill.apply",

    "customer_id": "STOtest001",

    "order_id": "ORD202306300001",

    "timestamp": "20230630120000",

    # ... 其他業務參數

}

secret_key = "YourSecretKey123456"



sign = generate_sto_sign(params, secret_key)

params['sign'] = sign  # 將簽名加入請求參數

Node.js 請求示例：

const axios = require('axios');

const crypto = require('crypto');

const qs = require('querystring');



async function createSTOWaybill() {

    const baseUrl = 'https://gateway.sto.cn/router/rest';

    const customerId = 'STOtest001';

    const secretKey = 'YourSecretKey123456';

    const method = 'stc.order.waybill.apply';



    // 1. 構建業務參數

    const businessParams = {

        order_id: ORDER_${Date.now()},
        sender: JSON.stringify({
            name: "發貨人",
            mobile: "13800000000",
            province: "上海",
            city: "上海市",
            district: "浦東新區",
            address: "張江高科技園區"
        }),
        receiver: JSON.stringify({
            name: "收貨人",
            mobile: "13900000000",
            province: "浙江",
            city: "杭州市",
            district: "余杭區",
            address: "阿里巴巴西溪園區"
        }),
        cargo: JSON.stringify({
            name: "電子產品",
            weight: "1.2",
            count: "1"
        }),
        service_type: "標準快遞",
        pay_type: "SHIPPER",
        need_tracking_info: "1"
    };

    // 2. 構建系統參數
    const systemParams = {
        method: method,
        customer_id: customerId,
        timestamp: new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 14), // YYYYMMDDHHmmss
        format: 'json',
        v: '1.0'
    };

    // 3. 合并參數并生成簽名
    const allParams = {...systemParams, ...businessParams};
    const sign = generateStoSign(allParams, secretKey);
    allParams.sign = sign;

    // 4. 發送請求
    try {
        const response = await axios.post(baseUrl, qs.stringify(allParams), {
            headers: {'Content-Type': 'application/x-www-form-urlencoded'}
        });
        console.log('運單創建成功：', response.data);
        return response.data;
    } catch (error) {
        console.error('運單創建失敗：', error.response?.data || error.message);
        throw error;
    }
}

function generateStoSign(params, secretKey) {
    // 過濾并排序參數
    const filtered = Object.keys(params)
        .filter(key => params[key] !== null && params[key] !== undefined && params[key] !== '')
        .sort()
        .map(key => ${encodeRFC3986(key)}=${encodeRFC3986(params[key])});

    const stringToSign = filtered.join('&');
    const signString = ${secretKey}${stringToSign}${secretKey};

    return crypto.createHash('md5')
        .update(signString, 'utf8')
        .digest('hex')
        .toUpperCase();
}

function encodeRFC3986(str) {
    return encodeURIComponent(str)
        .replace(/%20/g, '+')
        .replace(/[!'()*]/g, c => %${c.charCodeAt(0).toString(16).toUpperCase()});
}

// 執行運單創建
createSTOWaybill();

3. 物流軌跡實時查詢

核心接口： stc.trace.query
作用： 根據運單號查詢包裹的實時物流狀態和運輸歷史軌跡。

關鍵請求參數：

{

  "customer_id": "STOtest001",

  "tracking_number": "773123456789" // 申通運單號

}

響應數據結構示例：

{

  "success": true,

  "data": {

    "tracking_number": "773123456789",

    "order_id": "ORD202306300001",

    "latest_status": "派送中",

    "latest_time": "2023-06-30 14:30:00",

    "traces": [

      {

        "time": "2023-06-30 14:30:00",

        "description": "【杭州濱江公司】的派件員【王師傅 138****1234】正在派件",

        "location": "杭州濱江公司"

      },

      {

        "time": "2023-06-30 09:15:00",

        "description": "快件已到達【杭州轉運中心】",

        "location": "杭州轉運中心"

      },

      {

        "time": "2023-06-29 20:45:00",

        "description": "快件已從【深圳南山網點】發出，下一站【杭州轉運中心】",

        "location": "深圳南山網點"

      },

      {

        "time": "2023-06-29 18:20:00",

        "description": "【深圳南山網點】已收件",

        "location": "深圳南山網點"

      }

    ]

  }

}

4. 網點/服務查詢

接口示例：

• stc.network.serviceability.check： 查詢始發地到目的地是否可達及預估時效。
• stc.network.branch.list： 查詢指定區域內的申通網點信息。

5. 路由訂閱（Webhook）

核心機制： 并非單一接口，而是一種推送模式。
作用： 開發者需要在申通平臺配置回調URL。當運單狀態發生重要變更時，申通服務器會主動向該URL推送最新的物流事件信息。比輪詢更實時高效。

推送數據示例：

POST /your/callback/url HTTP/1.1

Content-Type: application/json



{

  "event": "TRACE_UPDATE", // 事件類型

  "tracking_number": "773123456789",

  "current_status": "SIGNED", // 最新狀態碼 (簽收)

  "current_description": "已簽收，簽收人：前臺",

  "current_time": "2023-06-30 16:05:00",

  "signature": "...", // 用于驗證推送來源合法性的簽名

  "timestamp": "20230630160500"

}

處理注意事項：

• 驗證簽名： 務必使用分配的secret_key驗證推送請求的簽名，防止偽造請求。
• 冪等處理： 由于網絡可能重傳，確保對重復事件的處理是冪等的（即多次處理同一事件結果一致）。
• 快速響應： 收到推送后，盡快返回HTTP 200狀態碼，避免申通服務器重試。

四、高級應用與最佳實踐

1. 面單模板定制

• HTML模板： 申通通常返回面單的HTML代碼。開發者可下載并解析此HTML，使用工具（如wkhtmltopdf, Headless Chrome）將其轉換為PDF或直接發送給熱敏打印機。
• 模板設計： 在申通電子面單平臺可自定義模板布局、LOGO、廣告語、二維碼內容等，設計好后將模板ID傳入下單接口。

2. 錯誤處理與重試機制

• 理解錯誤碼： 仔細處理申通API返回的業務錯誤碼（如 SERVICE_UNAVAILABLE, INVALID_PARAM, BIZ_ERROR）和HTTP狀態碼（如 401, 403, 429, 500）。
• 優雅降級： 在API調用失敗時，應有備用方案（如本地記錄日志、人工干預入口、切換備用快遞渠道）。
• 重試策略： 對于網絡超時或服務端錯誤（5xx），采用帶指數退避的有限次重試（如 1s, 2s, 4s 后重試）。

3. 性能優化

• 連接池： 使用HTTP客戶端連接池（如Apache HttpClient Pool, OkHttp Connection Pool）管理到申通API服務器的連接。
• 異步調用： 對于非即時響應的操作（如下單后獲取軌跡），可采用異步隊列處理（如Kafka, RabbitMQ, Redis Queue），避免阻塞主線程。
• 緩存： 對相對靜態的數據（如網點信息、服務類型列表）進行合理緩存，減少不必要的API調用。

4. 安全規范

• 密鑰管理： 絕對禁止將secret_key硬編碼在客戶端代碼或前端。使用安全的配置管理服務（如AWS Secrets Manager, HashiCorp Vault, K8s Secrets）或環境變量存儲。
• HTTPS： 確保所有API調用都通過HTTPS進行，防止信息被竊聽或篡改。
• 請求驗證： 在處理申通的Webhook推送時，必須驗證簽名。
• 權限最小化： 為API訪問配置必要的權限，避免過度授權。

五、典型應用場景

1. 電商平臺：

• 用戶下單后，自動調用申通API創建運單、獲取面單號。
• 訂單管理后臺集成物流軌跡，客服快速查看包裹狀態。
• 用戶中心提供“我的快遞”頁面，展示實時物流信息。
• 根據簽收狀態自動觸發確認收貨、結算流程。

2. ERP/WMS系統：

• 倉庫發貨時，批量調用申通API獲取運單號并打印面單。
• 將物流軌跡信息關聯到出庫單、銷售訂單。
• 根據網點、時效數據優化倉庫發貨路由策略。
• 物流異常狀態（如超時未更新）自動預警。

3. 跨境電商SaaS：

• 為多個賣家店鋪提供統一的申通快遞下單和軌跡查詢服務。
• 聚合多快遞商（申通+其他）軌跡，提供統一查詢界面。
• 基于物流數據生成運費分析、時效分析報表。

4. 線下門店/微商：

• 開發簡易打單工具，連接熱敏打印機快速打印申通面單。
• 手機APP掃描訂單即可完成快遞下單和軌跡查詢。

六、挑戰與注意事項

1. 文檔與規范： 快遞公司的API文檔質量可能參差不齊，更新也可能滯后。遇到問題時，積極聯系技術支持或查閱社區經驗至關重要。
2. 網絡穩定性： 快遞公司數據中心的網絡穩定性可能不如大型云廠商，需要做好調用失敗和重試的準備。建議設置合理的超時時間（如連接超時3s，讀超時10s）。
3. 字段兼容性： 不同快遞公司的接口字段命名、格式要求（如地址分級、電話號碼格式）可能不同。在對接多家快遞時，設計良好的適配層（Adapter）是關鍵。
4. 測試沙箱： 充分利用測試環境進行充分的功能、性能和異常測試。測試環境的業務規則（如地址校驗、下單限制）可能與生產環境略有差異。
5. 簽約與費率： API接入通常需要與申通簽署正式合作協議，明確結算方式（月結/預付）和運費費率。技術對接完成不代表可以立即發業務件。
6. 合規性： 確保用戶隱私數據（收寄件人信息）的收集、傳輸、存儲和使用符合《個人信息保護法》等相關法規要求。

七、總結

申通快遞API為開發者打開了將專業物流能力快速集成到各類應用系統的大門。從自動化下單打單，到實時精準的物流追蹤，再到數據驅動的運營分析，API的價值貫穿于物流管理的全鏈條。

成功集成的關鍵在于：透徹理解API文檔與簽名機制、編寫健壯的錯誤處理與重試邏輯、嚴格遵守安全規范、充分利用測試環境進行驗證、并針對具體業務場景進行合理的設計與優化。 當克服了文檔、網絡、兼容性等挑戰后，申通快遞API將成為提升業務效率和用戶體驗的強大助推器。

在萬物互聯的時代，API是連接服務的橋梁，而物流API正是連接虛擬訂單與現實交付的核心紐帶。 掌握申通快遞API，意味著你的應用具備了打通商業閉環“最后一公里”的關鍵能力。

#你可能也喜歡這些API文章!

REST API 基礎：定義、示例及使用方法

深入了解 Gateway API 的推理擴展