綠界金流、物流、電子發票三合一整合：架構該怎麼設計才不會後悔

綠界最大的賣點之一，是它同時提供金流、物流、電子發票三種服務。對中小型電商來說，用一個平台搞定所有事情確實很方便。但方便歸方便，三組 API 在技術層面是完全獨立的系統，各有各的串接規格、各有各的 Callback 網址、甚至各用不同組的 HashKey 和 HashIV。如果架構沒設計好，後面維護起來會非常痛苦。

先看一筆訂單的完整生命週期。消費者下單 → 選擇付款方式（金流 API）→ 付款成功 → 系統自動建立物流單（物流 API）→ 出貨寄件 → 消費者收到商品 → 系統自動開立電子發票（發票 API）。這三個步驟涉及三組完全不同的 API，而且每一步都有各自的 Callback 通知機制。金流有 ReturnURL，物流有 ServerReplyURL，發票有自己的回傳機制。你的系統必須能正確接收和處理來自三個不同來源的非同步通知，還要確保它們之間的觸發順序和狀態一致性。

架構上的第一個重點是「統一的 Callback 接收層」。雖然三組 API 的 Callback 格式和驗證方式不同，但建議在你的後端設計一個統一的 Webhook Receiver 模組，負責接收所有來自綠界的通知，驗證 CheckMacValue 後分派到對應的處理邏輯。這樣做的好處是日誌集中、錯誤處理一致、未來要換金流供應商也只需要改這一層。

第二個重點是「三組 HashKey/HashIV 的管理」。很多人不知道，即使是同一個 MerchantID，金流、物流、電子發票的 HashKey 和 HashIV 是不同的。如果你在程式裡用一個變數存所有的 HashKey，串金流的時候沒問題，串物流的時候 CheckMacValue 就會算錯。建議用一個設定檔或環境變數把三組金鑰分開管理，命名上也要清楚區分，例如 ECPAY_PAYMENT_HASH_KEY、ECPAY_LOGISTICS_HASH_KEY、ECPAY_INVOICE_HASH_KEY。

第三個重點是「觸發時機的設計」。什麼時候該觸發物流建單？什麼時候該開發票？這個看似簡單的問題，實際上涉及業務邏輯的決策。最常見的做法是：金流付款成功（ReturnURL 收到 RtnCode=1）→ 觸發物流建單；物流狀態更新為「消費者已取貨」→ 觸發開立發票。但如果是信用卡付款且商品是預購的，你可能不想在付款成功後立刻建物流單，而是等到商品到貨後再建單。這些時機點的設計必須跟業務方討論清楚再寫進程式裡。

第四個重點是「失敗處理與補償機制」。現實中，金流付款成功但物流建單失敗是可能發生的——例如物流 API 暫時掛掉、或者收件資訊格式有誤。如果沒有補償機制，這筆訂單就會卡在「已付款但未出貨」的狀態。建議設計一個重試佇列（Retry Queue），物流建單失敗時先放進佇列，定時重試幾次，超過重試上限就標記為異常通知客服人工處理。同樣的邏輯也適用於發票開立失敗的情況。

第五個重點是「資料表的設計原則」。建議把金流、物流、發票的資料分開儲存在不同的表，而不是全部塞進訂單表裡。訂單表只存核心業務資料（商品、金額、消費者資訊），金流表存交易編號和付款狀態，物流表存物流單號和配送狀態，發票表存發票號碼和開立狀態。三張表都用訂單編號做關聯。這樣做的好處是各自的狀態變更不會互相干擾，查詢和除錯也方便得多。

最後一個建議是「不要在第一版就串完三個」。很多團隊一開始就想一次到位，結果三個 API 同時串、同時 debug，時間和精力被分散得很薄。比較務實的做法是先串金流（這是讓營收開始跑的最關鍵環節），金流穩定後再串物流，最後再串發票。分階段上線不僅降低風險，也讓你有時間在每個階段驗證架構設計是否正確。