PHP 串接快遞100 API 查詢物流軌跡（支援 JSON 回傳）

PHP 串接快遞100 API 查詢物流軌跡（支援 JSON 回傳）

使用快遞100 移動端查詢介面，支援指定快遞公司代碼與單號，回傳結構化 JSON 資料。

封裝函式

<?php
/**
 * 查詢快遞物流資訊
 * @param string $code 快遞公司代碼（如 shunfeng, yuantong）
 * @param string $invoice 快遞單號
 * @return array ['status'=>1/0, 'info'=>'訊息', 'state'=>'狀態碼', 'data'=>軌跡陣列]
 */
function getExpressDelivery($code, $invoice) {
    $result = array('status' => 0, 'info' => '未知錯誤');
    // 移動端介面，隨機 temp 參數防快取
    $url = "https://m.kuaidi100.com/query?type={$code}&postid={$invoice}&id=1&valicode=&temp=" . rand(1, 710);
    $body = @file_get_contents($url);
    if ($body === false) {
        $result['info'] = '請求失敗';
        return $result;
    }
    $body = json_decode($body, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        $result['info'] = 'JSON 解析失敗';
        return $result;
    }
    $result['status'] = ($body['status'] == 200) ? 1 : 0;
    $result['info'] = $body['message'];
    if (isset($body['data'])) {
        $result['state'] = $body['state'];
        $result['data'] = $body['data'];
    }
    return $result;
}
?>

回傳結構說明

• status：1 成功、0 失敗
• info：錯誤訊息或「查詢成功」
• state：快遞100 狀態碼（0=查詢異常, 1=暫無軌跡, 2=派送中, 3=已簽收, 4=問題件）
• data：軌跡陣列，每項含 time、context（描述）、ftime（格式化時間）

使用範例

$res = getExpressDelivery('shunfeng', 'SF1234567890');
if ($res['status']) {
    foreach ($res['data'] as $track) {
        echo "{$track['ftime']} {$track['context']}
";
    }
} else {
    echo "查詢失敗：" . $res['info'];
}

注意事項

• 官方文檔另提供 HTML 介面，JSON 介面非公開文檔，可能變更。
• 高頻查詢建議申請企業版 API Key，並做本地快取降低依賴。
• 快遞公司代碼對照表請參考快遞100 官方文檔。