集運 API 開發者平台：用你自己的金鑰讀取集運與報關資料
免人工審查的集運 API——加「好運器集運官方帳號」LINE 好友即可自助申請金鑰，讓你的系統、OpenClaw 或 Hermes 直接讀取自己的帳單、包裹、預報與稅單。會員事件的 Webhook 推送仍在規劃中；貨況通知目前透過好運器 App 與 LINE 官方帳號送達。
免人工審查的集運 API——加「好運器集運官方帳號」LINE 好友即可自助申請金鑰，讓你的系統、OpenClaw 或 Hermes 直接讀取自己的帳單、包裹、預報與稅單。會員事件的 Webhook 推送仍在規劃中；貨況通知目前透過好運器 App 與 LINE 官方帳號送達。
好運器集運 API 讓會員用自己的金鑰，從自己的系統讀取自己在好運器的帳單、包裹、預報與稅單。門檻只有一個：加「好運器集運官方帳號」LINE 好友；免人工審查，金鑰效期 1 年，每把金鑰每分鐘 60 次、每日 5,000 次。
| 入口 | 適合誰 | 認證方式 | 能讀什麼 | 次數上限 |
|---|---|---|---|---|
會員資料 APIhttps://0523.tw/api/v1/me | 想讓自家系統、ERP、排程腳本讀自己資料的會員 | Bearer 金鑰（在 /member/api 自助建立） | 自己的帳單、包裹、預報、關稅稅單與進口報單 | 每把金鑰每分鐘 60 次、每日 5,000 次 |
會員 MCPhttps://0523.tw/mcp | 想用 Claude、ChatGPT 等 AI 助理查自己包裹的會員 | OAuth 2.1 授權，不用複製金鑰 | 和會員資料 API 相同，以 6 支唯讀工具提供 | 預設每分鐘 60 次、每日 5,000 次 |
公開 MCPhttps://0523.tw/mcp/public | 任何人、任何支援 MCP 的客戶端 | 免金鑰、免 OAuth | 運費與進口稅費試算、CCC 稅則與輸入規定、超材費、集運流程；不含任何會員資料 | 每個 IP 每分鐘 120 次 |
全部端點都是唯讀的 GET，Base URL 為 https://0523.tw/api/v1/me，回應為 JSON。
GET /api/v1/me：會員基本資料與 LINE 好友狀態，接線後建議先打這支確認金鑰有效。GET /api/v1/me/usage：這把金鑰目前的每分鐘與每日用量。GET /api/v1/me/bills、/bills/{code}：帳單列表與單張明細（帳單以會員手機歸戶，沒填手機會拿到空陣列與提示）。GET /api/v1/me/shipments：自己的集運包裹，可用 status 篩選已認領、已預報、已入倉、集運中、已出庫等狀態。GET /api/v1/me/forecasts：自己申報的集運預報。GET /api/v1/me/customs、/customs/{id}：關稅稅單與進口報單，可用 type 篩選。列表端點可分頁（per_page 上限 100），時間為台北時區，金額一律新台幣。新會員還沒有任何資料時回 200 與空陣列，不會報錯。個資預設遮罩：身分證字號只露前 3 碼與後 3 碼、地址只保留縣市、電話遮中段；稅單與報單欄位採白名單輸出，不含 OCR 原始全文。
每把金鑰分開計算，同時有「每分鐘 60 次」與「每日 5,000 次」兩道限制。超過任一道會收到 HTTP 429，並附 Retry-After 標頭告訴你幾秒後再試；成功回應也會附上剩餘次數的標頭，方便自己節流。請不要用高頻輪詢逼近上限來模擬即時更新。
MCP（Model Context Protocol）是讓 AI 助理呼叫外部工具的標準介面。好運器的會員 MCP 讀的是和集運 API 相同的資料，差別在授權方式：API 用你自己保管的金鑰，會員 MCP 則在好運器頁面用 OAuth 授權，AI 助理拿不到你的密碼或金鑰，門檻與次數上限和 API 相同。只想讓 AI 算運費、稅金或查稅則，用免金鑰的公開 MCP 即可。
不需要人工審查。登入會員後到 /member/api，帳號須已連結 LINE 並加「好運器集運官方帳號」為好友，輸入應用名稱、同意開發者條款就能建立金鑰。每個帳號最多同時保有 5 把有效金鑰。
金鑰效期 1 年，到期不支援續期，要重新建立。金鑰明文只在建立當下顯示一次，遺失無法找回，請在 /member/api 撤銷舊金鑰後重建一把新的。
每把金鑰每分鐘 60 次、每日 5,000 次，超過任一道就回 429，並附 Retry-After 標頭告訴你幾秒後再試。成功回應的標頭也會附剩餘次數，請依此節流，不要用高頻輪詢逼近上限。
會員資料相同，差在使用方式：自家系統、ERP 或排程腳本用 API 金鑰直接呼叫 REST 端點；想用 Claude、ChatGPT 等 AI 助理以對話方式查包裹，就接會員 MCP，以 OAuth 授權、不必複製金鑰，接法見〈集運 MCP 教學〉。只想算運費與稅金，用免金鑰的公開 MCP 即可。
不行。金鑰只能讀金鑰擁有者本人的資料，查不到或不屬於你的資料一律回 404。代理查詢、轉售存取權都違反開發者條款，好運器可逕行停權或撤銷金鑰。
會員事件的 Webhook 推送仍在規劃中。目前可以在 /member/api 設定並驗證網址，但系統還不會送出帳單、包裹狀態、放行等事件。上線前請以較低頻率定時查詢；包裹狀態通知目前透過好運器 App 與 LINE 官方帳號送達。
任何支援 MCP 的 AI 助理都能直接連上，不需帳號、不需 OAuth。提供台灣進口稅費、CCC 稅則與輸入規定、中國→台灣集運運費試算。
| 伺服器網址 | https://0523.tw/mcp/public |
|---|---|
| 傳輸方式 | Streamable HTTP |
| 驗證 | 不需要（免金鑰、免 OAuth） |
lucky_about |
好運器品牌與服務介紹 |
lucky_freight_quote |
中國→台灣集運運費試算（海快／空運） |
lucky_import_tax_estimate |
台灣進口稅費試算（關稅＋營業稅） |
lucky_ccc_tariff_lookup |
CCC 稅則號別 → 稅率與輸入規定 |
lucky_ccc_predict |
商品名稱 → CCC 稅則候選 |
lucky_hct_oversize_fee |
新竹物流台灣段超材費 |
lucky_workflow |
集運流程說明 |
lucky_simple_declaration |
台灣簡易申報規定 |
所有工具唯讀、冪等，不會變更任何資料。試算僅供參考：運費以入倉丈量後帳單為準、稅費以海關核定為準。
下方的會員版 MCP 需要 OAuth 綁定，回傳的是你自己的包裹、帳單與預報；公開 MCP 只提供公開資料（稅則、費率、法規），不含任何會員個人資料。
已登錄於官方 MCP Registry，名稱 tw.0523/lucky-public。