運費 API 開發文檔

能做什麼

• 運費試算 — 帶入包裹重量 (或長寬高材積),回傳該包裹的海快集運費 (人民幣)。
• 取得費率 — 查詢目前的每公斤費率、附加費門檻與材積換算係數,方便你在前端自行計算或快取。

所有回應皆為 JSON,採統一信封格式:成功時 success: true 並帶 data;失敗時 success: false 並帶 error 代碼與 message。

Base URL

認證標頭 (擇一)

方式 A — Bearer Token (建議)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

方式 B — X-API-Key

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

API Key 以 lk_live_ 開頭。請妥善保管,切勿放入前端 JavaScript 或公開的 Git 儲存庫;所有呼叫應由你的伺服器端發出。

速率限制 (Rate Limit)

每把金鑰有每分鐘請求上限,回應標頭會回報剩餘額度:

標頭	說明
X-RateLimit-Limit	每分鐘允許的請求數
X-RateLimit-Remaining	本分鐘剩餘請求數
Retry-After	超限時 (HTTP 429) 需等待的秒數

為求最佳前台體驗,建議將 /rates 結果快取數分鐘,並在自家伺服器以相同公式計算,僅在下單關鍵步驟才呼叫 /quote 核對。

GET /api/v1/freight/rates

列出目前所有啟用的運送方式與費率。無需任何參數。

請求

curl https://0523.tw/api/v1/freight/rates \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

回應 200

{
  "success": true,
  "currency": "CNY",
  "data": [
    {
      "method": "sea",
      "name_zh": "海快",
      "name_en": "Sea Express",
      "rate_per_kg": 10,
      "surcharge": 20,
      "min_threshold": 15,
      "volume_divisor": 10000,
      "currency": "CNY"
    }
  ]
}

GETPOST /api/v1/freight/quote

依包裹重量 / 材積尺寸計算海快集運費。GET (query string) 與 POST (JSON 或 form) 皆可。

請求參數

參數	型別	必填	說明
weight	number	選填*	實際重量,單位公斤 (kg)。
length	number	選填*	長,單位公分 (cm)。
width	number	選填*	寬,單位公分 (cm)。
height	number	選填*	高,單位公分 (cm)。
method	string	選填	運送方式,目前為 sea (海快)。省略時預設 sea。

請求範例 (GET)

curl "https://0523.tw/api/v1/freight/quote?weight=8&method=sea" \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

請求範例 (POST JSON)

curl -X POST https://0523.tw/api/v1/freight/quote \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"weight": 5, "length": 40, "width": 30, "height": 30}'

回應 200

{
  "success": true,
  "data": {
    "method": "sea",
    "method_name_zh": "海快",
    "method_name_en": "Sea Express",
    "currency": "CNY",
    "currency_symbol": "¥",
    "actual_weight": 5,
    "volume_weight": 3.6,
    "volume_divisor": 10000,
    "billable_weight": 5,
    "billable_basis": "actual",
    "rate_per_kg": 10,
    "freight": 50,
    "surcharge": 20,
    "surcharge_applied": true,
    "min_threshold": 15,
    "total_fee": 70
  }
}

回應欄位說明

欄位	說明
actual_weight	實際重量 (kg)。未提供則為 0。
volume_weight	材積 (體積) 重 (kg) = 長×寬×高 ÷ 10000。未提供尺寸則為 0。
billable_weight	計費重 (kg) = max(實重, 材積重)。
billable_basis	計費依據:actual (依實重) 或 volumetric (依材積)。
freight	基本運費 = 計費重 × 每公斤費率 (未含附加費)。
surcharge	本筆實際加收的附加費 (未觸發為 0)。
surcharge_applied	是否觸發附加費 (計費重 < 門檻)。
total_fee	最終應收運費 (人民幣,四捨五入到整數)。

HTTP	error	說明
401	missing_api_key	未帶 API Key。請加 Authorization 或 X-API-Key 標頭。
401	invalid_api_key	API Key 無效。
403	key_suspended / key_revoked / key_expired	金鑰已停用 / 撤銷 / 過期。
403	insufficient_scope	金鑰未開通 freight:read 權限。
422	validation_failed	參數格式錯誤 (型別、範圍)。
422	missing_parameters	未提供 weight 或完整 length/width/height。
422	unsupported_method	method 不在可用清單。
429	rate_limit_exceeded	超過每分鐘請求上限,見 Retry-After。

0337.tw 為 Laravel 商城。建議將運費 API 包成一個後端 Service,在結帳流程呼叫:

• 於結帳取得購物車總重 (kg) / 材積後,在後端呼叫 /api/v1/freight/quote,把回傳的 total_fee 設為運費。
• 金鑰放在 .env (例如 LUCKY_FREIGHT_KEY),用 config() 讀取,不要寫死在程式碼或前端。
• 呼叫失敗 (逾時 / 429) 時,以 /rates 快取下來的費率在本地用同一公式計算作為後備,確保結帳不中斷。
• 金額為人民幣;若商城以新台幣結帳,請自行套用匯率換算。

Laravel 範例 (Http facade)

// app/Services/LuckyFreightService.php
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Cache;

class LuckyFreightService
{
    public function quote(float $weight): int
    {
        $res = Http::withToken(config('services.lucky.freight_key'))  // 讀 .env
            ->acceptJson()
            ->timeout(8)
            ->get('https://0523.tw/api/v1/freight/quote', [
                'weight' => $weight,
                'method' => 'sea',
            ]);

        if ($res->successful()) {
            return (int) $res->json('data.total_fee');  // 人民幣
        }

        // 後備:用快取費率本地計算,結帳不中斷
        return $this->fallbackQuote($weight);
    }
}

在 config/services.php 加 'lucky' => ['freight_key' => env('LUCKY_FREIGHT_KEY')],即可於結帳 Controller 注入 LuckyFreightService 取得運費。

技術支援: howyunqisoftware@gmail.com

API 版本: v1 (穩定)。任何破壞性變更將以新版號 (v2) 發布,v1 維持相容。

變更紀錄: 2026-06-01 — 運費 API v1 上線 (海快,人民幣計價)。