貨況查詢 API 開發文檔

包裹旅程

API 會依單號自動判斷包裹處於哪個階段,回傳當前狀態、完整時間軸,以及 (若已進入台灣海關) GC329 五階段通關進度。

Base URL

認證標頭 (擇一)

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

請由伺服器端呼叫,切勿將金鑰放入前端 JavaScript。速率限制以金鑰為單位,回應標頭 X-RateLimit-Remaining 會回報剩餘額度;超限回 HTTP 429。

GETPOST /api/v1/shipment/track

依單號查詢單一包裹貨況。GET (query string) 與 POST (JSON / form) 皆可。

請求參數

參數	型別	必填	說明
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	狀態代碼 (依來源不同,見下節)。建議以 status、is_delivered、is_final 驅動 UI。
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 會帶出五階段進度與整體百分比:

{
  "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 Key。
403	insufficient_scope	金鑰未開通 shipment:read 權限。
404	not_found	查無此單號,或包裹尚未進入集運系統。
422	validation_failed	缺少 tracking_number 或格式不符。
429	rate_limit_exceeded	超過每分鐘請求上限,見 Retry-After。

• 輪詢頻率:同一單號建議每 15–30 分鐘查一次即可;結果在本服務端有 5 分鐘快取 (cached: true 表示命中)。
• 停止輪詢:當 is_final = true (已簽收 / 退回 / 取消) 時停止輪詢。
• 狀態驅動:以 status 字串顯示、以 is_delivered / is_final 判斷流程,避免硬編 status_code (不同來源代碼定義不同)。
• 查無單號:404 多半代表包裹尚未進入集運系統 (客戶剛下單未寄出),可稍後重試。

技術支援: howyunqisoftware@gmail.com

API 版本: v1 (穩定)。

變更紀錄: 2026-06-01 — 貨況查詢 API v1 上線。