PHP 查詢快遞物流資訊：整合快遞100 API 完整範例

前言

電商、物流系統常需即時查詢包裹狀態。快遞100（kuaidi100.com）提供免費查詢介面，本文示範 PHP 整合其 API 並封裝為可重用函式。

API 介面說明

• 查詢端點： https://m.kuaidi100.com/query
• 必要參數： type（快遞公司代碼）、postid（運單號）
• 回傳格式： JSON
• 常用快遞代碼： shentong(申通)、yuantong(圓通)、zhongtong(中通)、yunda(韻達)、ems(EMS)、shunfeng(順豐)

封裝函式完整實作

<?php
/**
 * 查詢快遞物流軌跡
 * 
 * @param string $code 快遞公司代碼（如 shentong, yuantong）
 * @param string $invoice 運單號碼
 * @return array 統一格式回傳
 *   [
 *     'success' => bool,     // 查詢是否成功
 *     'message' => string,   // 狀態訊息
 *     'state' => int,        // 物流狀態碼（0:查詢失敗, 1:暫無軌跡, 2:在途, 3:簽收, 4:問題件）
 *     'data' => array        // 物流軌跡陣列
 *   ]
 */
function getExpressDelivery($code, $invoice) {
    // 1. 參數驗證
    if (empty($code) || empty($invoice)) {
        return ['success' => false, 'message' => '參數不完整', 'state' => 0, 'data' => []];
    }

    // 2. 建構請求 URL（加入隨機參數防快取）
    $url = "https://m.kuaidi100.com/query" . http_build_query([
        'type' => $code,
        'postid' => $invoice,
        'id' => 1,
        'valicode' => '',
        'temp' => mt_rand(1, 9999),
    ]);

    // 3. 發送請求（建議生產環境用 cURL 替代，支援逾時控制）
    $context = stream_context_create([
        'http' => [
            'timeout' => 10, // 10 秒逾時
            'header' => "User-Agent: Mozilla/5.0\r\nReferer: https://m.kuaidi100.com\r\n"
        ]
    ]);
    
    $response = @file_get_contents($url, false, $context);
    
    if ($response === false) {
        return ['success' => false, 'message' => '網路請求失敗或逾時', 'state' => 0, 'data' => []];
    }

    // 4. 解析 JSON 回應
    $result = json_decode($response, true);
    
    if (json_last_error() !== JSON_ERROR_NONE) {
        return ['success' => false, 'message' => '回應格式錯誤', 'state' => 0, 'data' => []];
    }

    // 5. 統一回傳格式
    $status = $result['status'] ?? 0; // 200 成功, 400 參數錯誤, 500 伺服器錯誤等
    $isSuccess = ($status == 200);

    return [
        'success' => $isSuccess,
        'message' => $result['message'] ?? '未知錯誤',
        'state' => $isSuccess ? ($result['state'] ?? 0) : 0,
        'data' => $isSuccess ? ($result['data'] ?? []) : [],
    ];
}
?>

使用範例與結果處理

<?php
// 查詢範例
$tracking = getExpressDelivery('yuantong', 'YT1234567890123');

if ($tracking['success']) {
    echo "✅ 查詢成功！當前狀態碼: {$tracking['state']}\n";
    echo "狀態說明: " . getStateText($tracking['state']) . "\n\n";
    
    echo "📦 物流軌跡：\n";
    foreach ($tracking['data'] as $item) {
        $time = $item['time'] ?? '未知時間';
        $context = $item['context'] ?? '無描述';
        echo "  [{$time}] {$context}\n";
    }
} else {
    echo "❌ 查詢失敗: {$tracking['message']}\n";
}

// 狀態碼對照表
function getStateText($state) {
    $map = [
        0 => '查詢失敗/異常',
        1 => '暫無物流軌跡',
        2 => '在途運輸中',
        3 => '已簽收/妥投',
        4 => '問題件（退件/拒收/地址錯誤等）',
    ];
    return $map[$state] ?? "未知狀態({$state})";
}
?>

輸出範例

✅ 查詢成功！當前狀態碼: 2
狀態說明: 在途運輸中

📦 物流軌跡：
  [2024-01-15 08:30:00] 【北京分撥中心】 已發出,下一站 【上海轉運中心】
  [2024-01-15 14:22:00] 【上海轉運中心】 已到達
  [2024-01-16 09:15:00] 【上海浦東派送部】 正在派送,派送員:王小明 138xxxx5678
  [2024-01-16 12:05:00] 【已簽收】 簽收人:收件人本人,地點:前台

生產環境強化建議

常見快遞公司代碼對照表

$expressCodes = [
    'shentong' => '申通快遞',
    'yuantong' => '圓通速遞',
    'zhongtong' => '中通快遞',
    'yunda' => '韻達快遞',
    'shunfeng' => '順豐速運',
    'ems' => 'EMS 郵政',
    'tiantian' => '天天快遞',
    'huitong' => '百世快遞',
    'quanfeng' => '全峰快遞',
    'debang' => '德邦物流',
    'zhaijisong' => '宅急送',
    'youzhengguonei' => '郵政包裹/平郵',
];
// 完整代碼請參考快遞100 官方文件

整合快遞查詢功能不複雜，關鍵在於異常處理、快取策略與介面穩定性保障，建立健全的物流查詢服務層能大幅提升用戶體驗。