送料 API 開発ドキュメント

できること

• 送料試算 — 荷物の重量（または長さ・幅・高さによる容積）を渡すと、その荷物の海上速達の転送料金（人民元）を返します。
• 料率の取得 — 現在の 1kg あたりの料率、追加料金のしきい値、容積重量の換算係数を取得できます。フロントエンドでの自前計算やキャッシュに便利です。

レスポンスはすべて JSON で、共通のエンベロープ形式です。成功時は success: true と data、失敗時は success: false と error コード、message を返します。

Base URL

認証ヘッダー（いずれか一方）

方法 A — ベアラー トークン (推奨)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

方法 B — X-API キー

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

API キーは lk_live_ で始まります。厳重に管理し、フロントエンドの JavaScript や公開 Git リポジトリには絶対に含めないでください。呼び出しはすべて自社のサーバー側から行ってください。

レート制限（Rate Limit）

キーごとに 1 分あたりのリクエスト上限があり、残り回数はレスポンスヘッダーで確認できます：

ヘッダー	説明
X-RateLimit-Limit	1 分あたりに許可されるリクエスト数
X-RateLimit-Remaining	この 1 分間の残りリクエスト数
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（クエリ文字列）と POST（JSON またはフォーム）のどちらでも利用できます。

リクエストパラメータ

パラメータ	型	必須	説明
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	基本送料 = 請求重量 × 1kg あたりの料率（追加料金は含みません）。
surcharge	この荷物に実際に加算された追加料金（発生しない場合は 0）。
surcharge_applied	追加料金が発生したかどうか（請求重量 < しきい値）。
total_fee	最終的な請求送料（人民元、整数に四捨五入）。

HTTP	error	説明
401	missing_api_key	API キーが指定されていません。Authorization または X-API-Key ヘッダーを追加してください。
401	invalid_api_key	API キーが無効です。
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	1 分あたりのリクエスト上限を超えました。Retry-After を確認してください。

0337.tw は Laravel 製の EC サイトです。送料 API をバックエンドの Service としてまとめ、チェックアウト処理で次のように呼び出すことをおすすめします：

• チェックアウト時にカートの総重量（kg）／容積を取得したら、バックエンドから /api/v1/freight/quote を呼び出し、返ってきた total_fee を送料として設定します。
• キーは .env（例：LUCKY_FREIGHT_KEY）に置き、config() で読み込みます。コードやフロントエンドに直接書き込まないでください。
• 呼び出しに失敗した場合（タイムアウト／429）は、/rates でキャッシュしておいた料率を使い、同じ計算式でローカル計算してチェックアウトが止まらないようにします。
• 金額は人民元です。EC サイトで新台湾ドル決済を行う場合は、自社で為替レートを適用して換算してください。

Laravel の例 (HTTP ファサード)

// 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 を公開（海上速達、人民元建て）。