荷物追跡 API 開発ドキュメント

荷物の流れ

API が追跡番号から荷物の現在の段階を自動で判定し、現在のステータス、全体のタイムライン、（台湾税関に入っている場合は）GC329 の 5 段階の通関進捗を返します。

Base URL

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

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx
// 或
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

必ずサーバー側から呼び出し、キーをフロントエンドの JavaScript に含めないでください。レート制限はキー単位で、残り回数はレスポンスヘッダー X-RateLimit-Remaining で確認できます。上限を超えると HTTP 429 を返します。

GETPOST /api/v1/shipment/track

追跡番号で荷物 1 件の状況を照会します。GET（クエリ文字列）と POST（JSON／フォーム）のどちらでも利用できます。

リクエストパラメータ

パラメータ	型	必須	説明
tracking_number	string	必須	荷物の追跡番号（4〜64 文字、英数字と - _）。中国の宅配便追跡番号／顧客注文番号／運送業者の追跡番号のいずれも使えます。

リクエスト例(GET)

curl "https://0523.tw/api/v1/shipment/track?tracking_number=SF1234567890123" \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

応答 200 (例はすでに倉庫にある/輸送中)

{
  "success": true,
  "cached": false,
  "tracking_number": "SF1234567890123",
  "data": {
    "tracking_number": "SF1234567890123",
    "customer_order_no": "LK260601001",
    "carrier_tracking_no": "SF1234567890123",
    "logistics": "順豐速運",
    "status_code": 2,
    "status": "已入倉",
    "description": "包裹已進入深圳集運倉,等待集運打包",
    "is_delivered": false,
    "is_final": false,
    "last_event_time": "2026-06-01 12:30:00",
    "updated_at": "2026-06-01 12:31:05",
    "timeline": [
      { "name": "已攬收", "completed": true,  "time": "2026-05-30 09:00:00" },
      { "name": "已入倉 (深圳集運倉)", "completed": true,  "time": "2026-06-01 12:30:00" },
      { "name": "集運打包/台灣運送", "completed": false, "time": null },
      { "name": "已簽收", "completed": false, "time": null }
    ],
    "customs_stages": null,
    "events": null
  }
}

応答 404 (注文番号が見つかりません)

{
  "success": false,
  "error": "not_found",
  "message": "查無此單號。請確認單號正確,或包裹尚未進入集運系統。",
  "tracking_number": "SF1234567890123"
}

フィールド	型	説明
status	string	現在のステータス（人が読める文字列）。例：「已預報」「已入倉」「運輸中」「台灣派送中」「已簽收」（順に事前登録済み／入庫済み／輸送中／台湾で配送中／受取済み）。この文字列をそのまま表示することをおすすめします。
status_code	number	ステータスコード（データソースによって異なります。次の節を参照）。UI の制御には status、is_delivered、is_final を使うことをおすすめします。
is_delivered	bool	受取済みかどうか。
is_final	bool	最終状態（受取済み／返送／キャンセル／配達不能）かどうか。true ならポーリングを停止できます。
logistics	string	物流業者（中国の宅配便、または台湾のラストワンマイル配送）。
description	string	最新イベントの説明。
last_event_time	datetime	直近の物流イベントの日時。
timeline	array	段階ごとのタイムライン。各項目に name / completed / time / description を含みます。
customs_stages	object|null	台湾税関 GC329 の通関進捗（通関前は null）。次の節を参照。
events	array|null	未加工の物流イベント履歴（ラストワンマイル配送の追跡時に提供）。

転送の主な段階（timeline）

段階	意味
事前登録済み（未入庫）	顧客が追跡番号を事前登録済みで、荷物はまだ深圳の転送倉庫に届いていません。
入庫済み（深圳の転送倉庫）	深圳の転送倉庫が荷物を受け取りました。
転送用に梱包／台湾へ輸送	梱包して出荷し、海上輸送／航空輸送で台湾へ送ります。
輸送中／台湾で配送中	台湾到着後の通関と、ラストワンマイル配送の段階です。
受取済み	受取人が受け取りました（is_delivered = true）。

税関の通関段階（customs_stages、GC329）

荷物が台湾税関に入ると、customs_stages に 5 段階の進捗と全体の進捗率が含まれます：

{
  "hbl": "691MK539819",
  "trans_type_name": "海運",
  "current_stage_name": "海關放行",
  "progress_percent": 80,
  "is_completed": false,
  "stages": [
    { "code": "XX", "name": "船(機)抵達",   "done": true },
    { "code": "E1", "name": "連線收單建檔", "done": true },
    { "code": "D1", "name": "計稅",        "done": true },
    { "code": "RL", "name": "海關放行",     "done": true },
    { "code": "OW", "name": "出倉",        "done": false }
  ],
  "source": "關港貿單一窗口 GC329"
}

HTTP	error	説明
401	missing_api_key / invalid_api_key	API キーがないか、無効です。
403	insufficient_scope	キーに shipment:read 権限が付与されていません。
404	not_found	この追跡番号が見つからないか、荷物がまだ転送システムに登録されていません。
422	validation_failed	tracking_number がないか、形式が正しくありません。
429	rate_limit_exceeded	1 分あたりのリクエスト上限を超えました。Retry-After を確認してください。

• ポーリング頻度：同じ追跡番号の照会は 15〜30 分に 1 回で十分です。結果はこのサービス側で 5 分間キャッシュされます（cached: true はキャッシュヒットを示します）。
• ポーリングの停止：is_final = true（受取済み／返送／キャンセル）になったらポーリングを停止してください。
• ステータスで判断：表示には status の文字列を使い、処理の分岐は is_delivered / is_final で判断してください。status_code のハードコードは避けてください（データソースごとにコードの定義が異なります）。
• 番号が見つからない場合：404 の多くは、荷物がまだ転送システムに登録されていないことを意味します（顧客が注文した直後で未発送など）。しばらくしてから再試行してください。

技術サポート： howyunqisoftware@gmail.com

API バージョン： v1（安定版）。

変更履歴： 2026-06-01 — 荷物追跡 API v1 を公開。