Commerce Gateway 開發者串接手冊 (物流・金流・電子發票)

Public Integration Guide & API Reference

AI 提示：您可以直接將此頁面純文字網址 /docs/raw 提供給 ChatGPT、Claude 或 Cursor，讓 AI 自動為您的網站產生完整物流、金流與電子發票串接代碼！

載入中...

\n\n\n

訂單處理中...

\n\n \n\n\n```\n\n---\n\n### 7. 純前端兩種電商購物流程完整架構（貨到付款 vs 線上金流）\n\n純前端網站（無後端伺服器）或 Headless 靜態架構，可依據買家的付款方式無縫實現以下兩種全自動化閉環：\n\n#### 🛒 流程 A：貨到付款（COD）全自動流程\n1. **買家結帳下單**：\n - 前端收集買家收件地址、電話與發票設定（載具/統編/捐贈）。\n - 前端以 `pk_live_...` 直接呼叫 `POST /v1/shipments`（附帶 `\"is_cod\": true`, `\"cod_amount\": 1500`, 以及 `\"invoice_draft\": { ... }`）。\n - Gateway 立即向物流商（黑貓）立案取號，回傳 12 碼託運單號與面單 PDF 網址。\n2. **倉管出貨與列印分流**：\n - 倉管在 `/portal` 訂單工作台一鍵印出黑貓託運單。\n - **紙本/統編**：若買家有填寫統編或指定紙本發票，工作台顯示「開票並印單」，出貨時一鍵連同發票證明聯隨貨附寄。\n - **雲端載具/愛心捐贈**：工作台顯示「免印・配達自動開」，出貨時無需列印發票。\n3. **5 分鐘背景輪詢偵測配達自動開立發票**：\n - 商家可在 `/portal` 電子發票設定中開啟 **「貨到付款 / 包裹配達自動開立載具發票 (預設關閉)」**。\n - 司機順利送達買家（黑貓狀態碼 `301` 配達 / 7-11 門市取件完成 `211`）時，Gateway 背景排程在同一微秒內自動為該訂單開出綠界雲端載具或愛心捐贈發票。\n - 依法規已隨貨寄送之紙本統編發票會被自動略過，絕不重複開立！\n\n---\n\n#### 💳 流程 B：線上金流（信用卡 / ATM / 超商代碼）草稿轉正式單流程\n1. **買家送出訂單（先建立出貨草稿）**：\n - 前端在跳轉金流前，以 `pk_live_...` 先呼叫 `POST /v1/shipments/draft`（或 `POST /v1/shipments` 帶入 `\"is_draft\": true`）。\n - 系統將買家姓名、手機、收件地址/超商門市與發票草稿存入 Gateway（`status = 'draft'`）。\n - **完全不向黑貓 API 取單、不佔用物流單號額度**，並完整保留未結帳之買家聯絡資料以供後續購物車挽回！\n2. **導向金流收銀台付款**：\n - 前端緊接著呼叫 `POST /v1/payments/checkout` 取得 `checkout_url`，並將買家導向金流收銀台付款。\n3. **ATM 虛擬帳號 / 超商代碼取號即時展示 (純前端感謝頁)**：\n - 買家在收銀台取號後跳回感謝頁（網址自帶 `?merchant_order_id=...`），純前端使用 `pk_live_...` 呼叫 `GET /v1/payments/:id`，秒級取得 `payment_info`（銀行代號、虛擬帳號、繳費截止日），在感謝頁即時渲染展示！\n4. **付款成功：Gateway 自動轉單與開票**：\n - 買家完成付款後，綠界通知 Gateway 回呼端點，系統在同一時間點自動完成兩大作業：\n ① **自動線上開立發票**：不論是載具、捐贈或公司統編，發票立即線上開出並寄送通知。\n ② **自動草稿轉正**：自動將原先的出貨草稿向黑貓正式取單號與面單 PDF，狀態由 `draft` 升級為 `created`。\n ③ 自動發送 `shipment.created` 與 `payment.paid` Webhook 通知。\n5. **商家出貨**：\n - 商家在 `/portal` 訂單工作台看到訂單即時轉為「已付款」，託運單面單按鈕立即解鎖，一鍵列印出貨！\n\n> 💡 **後端網站分開送相容性**：\n> 若您的自建後端或 ERP 選擇「下單先送金流，等收到付款成功 Webhook 後才打入物流與發票」，Gateway 亦完全原生相容！金流付款時若資料庫中無出貨草稿，系統會自動優雅略過，不影響後續後端直接傳入正式單。\n\n---\n\n## 🤖 讓 AI 幫您寫程式的專用 Prompt (複製即可使用)\n\n當您要把串接工作交給 ChatGPT、Claude 或 Cursor 時，您可以直接複製以下文字：\n\n```markdown\n你好！我目前需要將我的電商網站串接到自建的「Commerce & Logistics Gateway 物流・金流・電子發票三合一中繼平台」，請先讀取以下完整 API 規格手冊並為我撰寫串接邏輯：\n\n1. 完整手冊網址 (純文字 Markdown): https://gateway.melontech.tw/docs/raw\n2. Gateway Base URL: https://gateway.melontech.tw\n3. 認證 Header: Authorization: Bearer (或純前端使用 pk_live_...)\n * ⚠️ 安全規範：請提示使用者另外於伺服器環境變數 (例如 .env 的 GATEWAY_SECRET_KEY) 中設定後端金鑰 (sk_live_...)，切勿寫死在程式碼或公開專案中！\n4. 三大核心模組 API：\n - 【📦 物流服務】建立正式託運單 POST /v1/shipments、建立出貨草稿單 POST /v1/shipments/draft (線上金流未付款前預存資料，不佔單號額度)、批量建單 POST /v1/shipments/batch、作廢託運單 POST /v1/shipments/:id/cancel、7-11 電子地圖 GET /v1/emap/7-11\n - 【💳 全方位金流支付】建立結帳單 POST /v1/payments/checkout\n * 支援 payment_method: \"ALL\"(全功能收銀台)、\"Credit\"(信用卡，可帶 installment_periods: \"3,6,12\" 分期)、\"ATM\"(虛擬帳號)、\"CVS\"(超商代碼)、\"BARCODE\"(超商條碼)、\"TWQR\"(行動支付)、\"ApplePay\"、\"BNPL\"(無卡分期)、\"WebATM\"\n * 純前端零信任防禦：前端結帳請帶入 items 陣列 (包含 sku、count、price) 與 service_type (\"home_delivery\" 宅配或 \"store_pickup\" 超取)，運費與冷鏈最高溫層由 Gateway 依商家的 prices.json 自動推導與防偽校驗，買家無法篡改運費\n * 回傳 data.checkout_url，直接將買家瀏覽器導向該網址即進入收銀台結帳；買家付款完成後 Gateway 會自動跳回 client_back_url (並在網址後方附帶 merchant_order_id, amount, status, trade_no 等參數)\n * 支援純前端感謝頁快速查詢 GET /v1/payments/:id (秒級取得 ATM 虛擬帳號、銀行代碼與繳費期限)\n * 買家付款成功時，Gateway 自動線上開立發票並將出貨草稿轉為正式待出貨單\n * 支援主動查詢 POST /v1/payments/query 與信用卡退刷 POST /v1/payments/refund\n - 【🧾 B2C 雲端電子發票】開立雲端發票 POST /v1/invoices/issue (支援會員/平台載具 carrier_type=\"1\"、手機條碼 carrier_type=\"3\"、自然人憑證 \"2\"、統編 buyer.identifier、愛心碼 donation=\"1\"；內建 merchant_order_id 冪等防重開保護)、列印發票 POST /v1/invoices/print、作廢 POST /v1/invoices/void、折讓 POST /v1/invoices/allowance、驗證條碼 POST /v1/invoices/verify-code\n5. Webhook 自動推播接收端:\n - 平台會以 POST 發送以下事件到我的伺服器 (附帶 Header `X-Logistics-Signature: sha256=`)：\n * `shipment.created`: 草稿轉正或出貨單建立成功 (內含 tracking_number, label_url)\n * `shipment.status_updated`: 包裹貨態異動\n * `payment.paid`: 金流付款成功\n * `payment.code_issued`: ATM 虛擬帳號或超商代碼/條碼取號成功 (內含 extra_info.bank_code, v_account, payment_no, expire_date)\n * `invoice.issued`: 發票開立完成通知 (內含 data.merchant_order_id, invoice_no, invoice_date, random_number)\n\n請幫我為 [我的框架/系統，例如: WooCommerce / Next.js / Laravel] 撰寫一個完整的服務模組！\n```\n"; document.addEventListener('DOMContentLoaded', () => { marked.setOptions({ highlight: function(code, lang) { const language = highlight.getLanguage(lang) ? lang : 'plaintext'; return highlight.highlight(code, { language }).value; }, langPrefix: 'hljs language-' }); document.getElementById('content').innerHTML = marked.parse(rawMarkdown); }); function copyPromptUrl() { const url = window.location.origin + '/docs/raw'; navigator.clipboard.writeText(url); alert('已複製 AI 專用純文字手冊網址：\n' + url + '\n\n您可直接貼給 ChatGPT / Claude！'); }