PHP 串接快遞100 API 查詢物流資訊實作教學

前言

電商、ERP 系統常需整合物流查詢功能。快遞100（Kuaidi100）提供免費 API，支援超過 1000 家物流商，回傳 JSON 格式，整合極為簡單。本文示範以 PHP 串接查詢物流軌跡。

API 介紹

• 請求網址：https://m.kuaidi100.com/query
• 參數：
  • type：快遞公司代碼（如 sf 順豐、yto 圓通）
  • postid：運單號碼
  • id：固定為 1
  • valicode：驗證碼（選填）
  • temp：隨機數防快取
• 回傳格式：JSON，包含 status、message、state、data（陣列）

PHP 封裝函式

<?php
/**
 * 查詢快遞物流資訊
 * @param string $code 快遞公司代碼
 * @param string $invoice 運單號碼
 * @return array 結構化結果
 */
function getExpressDelivery($code, $invoice) {
    $result = ['status' => 0, 'info' => '未知錯誤', 'state' => '', 'data' => []];
    
    $url = sprintf(
        'https://m.kuaidi100.com/query?type=%s&postid=%s&id=1&valicode=&temp=%d',
        urlencode($code),
        urlencode($invoice),
        mt_rand(1, 9999)
    );
    
    $json = @file_get_contents($url);
    if ($json === false) {
        $result['info'] = '網路請求失敗';
        return $result;
    }
    
    $data = json_decode($json, true);
    if (!$data) {
        $result['info'] = 'JSON 解析失敗';
        return $result;
    }
    
    // 狀態碼 200 代表成功
    if (($data['status'] ?? 0) == 200) {
        $result['status'] = 1;
        $result['info'] = $data['message'] ?? '查詢成功';
        $result['state'] = $data['state'] ?? '';
        $result['data'] = $data['data'] ?? [];
    } else {
        $result['info'] = $data['message'] ?? '查詢失敗';
    }
    
    return $result;
}

// 使用範例
$res = getExpressDelivery('sf', 'SF1234567890');
if ($res['status']) {
    echo "狀態：{$res['state']}\n";
    foreach ($res['data'] as $item) {
        echo "{$item['time']} {$item['context']}\n";
    }
} else {
    echo "錯誤：{$res['info']}\n";
}
?>

進階：支援 HTTPS 與 cURL 版本

生產環境建議使用 HTTPS 並加入超時控制：

function getExpressDeliveryCurl($code, $invoice) {
    $url = 'https://m.kuaidi100.com/query';
    $params = [
        'type' => $code,
        'postid' => $invoice,
        'id' => 1,
        'temp' => mt_rand(1, 9999)
    ];
    
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url . '?' . http_build_query($params),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_SSL_VERIFYPEER => false, // 若憑證驗證失敗可暫時關閉
        CURLOPT_USERAGENT => 'Mozilla/5.0 (PHP/' . PHP_VERSION . ')'
    ]);
    
    $json = curl_exec($ch);
    $err = curl_error($ch);
    curl_close($ch);
    
    if ($err) return ['status' => 0, 'info' => 'cURL 錯誤: ' . $err];
    return json_decode($json, true) ?: ['status' => 0, 'info' => '解析失敗'];
}

快遞公司代碼對照表（常用）

完整代碼請參考快遞100 官方文件。

錯誤碼對照

• 200：查詢成功
• 400：參數錯誤
• 500：伺服器錯誤
• 501：單號不存在或已過期
• 502：快遞公司代碼錯誤

注意事項

1. 免費版有頻率限制，高流量請申請企業版 API Key。
2. 部分物流商需攜帶 valicode 驗證碼，需先呼叫驗證碼介面。
3. 建議快取查詢結果 10-30 分鐘，減少 API 呼叫。
4. 生產環境務必加入錯誤重試與日誌記錄。