API 串接

可行性評估比報價更重要

API 串接的專案最容易失敗的原因，不是網站端做不出來，而是對方端的條件與預期不符——沒有需要的功能、沒有文件、沒有測試環境、或根本聯絡不到人。

這些都是報價前就該確認的事。以下是一份可以直接拿去問的清單。

一、對方端的基本條件

1. 有沒有提供 API？ 是公開的，還是需要申請
2. 有沒有技術文件？ 文件是否完整、是否為最新版
3. 有沒有測試環境？ 這一項很關鍵，見下方說明
4. 需要什麼資格才能申請？ 是否須為特定等級的客戶或付費方案
5. 有沒有額外費用？ 開通費、月費、按次計費
6. 有沒有技術窗口？ 出問題時找得到人嗎

測試環境為什麼重要

沒有測試環境，就只能用正式資料測試——這代表測試過程可能產生真實的訂單、真實的扣款、真實的出貨。

如果對方沒有提供，要先討論替代方案，並把風險納入評估。

二、功能面的確認

• 需要的每一個動作，API 都支援嗎？ 例如「查詢庫存」有，但「更新庫存」可能沒有
• 資料欄位夠嗎？ 你要的欄位對方是否提供
• 有沒有呼叫頻率的限制？ 每分鐘或每日的上限是多少
• 單次可以處理多少筆？ 大量資料是否需要分批
• 回應速度如何？ 太慢會影響網站的使用體驗

頻率限制是最常被忽略的一項。 如果限制是每分鐘幾次，而你有上千筆商品需要同步，那就不能即時處理，必須改成排程分批。這會直接影響架構設計。

三、把需求寫成具體的清單

「跟 ERP 串接」這句話無法報價。要拆解成具體的動作：

這張表就是報價與驗收的依據。 沒有它，報價只能是估算，驗收也沒有標準。

四、資料對應的落差

兩套系統的資料結構幾乎不會完全一致，需要事先確認：

• 編號規則是否一致——網站的商品編號與 ERP 的料號能對得起來嗎
• 規格與選項的表達方式——一邊用單一料號，一邊用「商品加規格」的結構
• 價格——含稅或未稅、幣別、是否有多組價格
• 分類架構——兩邊的分類方式不同時怎麼對應
• 必填欄位——一邊必填但另一邊可能沒有這個資料

這一段的落差越大，開發成本越高。 有時候調整其中一邊的資料規則，會比寫複雜的轉換邏輯划算得多。

五、誰負責對方端

這是責任邊界的問題，務必在發包時講清楚：

• 對方端的設定、開通、參數提供，由誰負責溝通？
• 對方端如果需要客製調整，費用由誰承擔？
• 對方端出問題時，網頁設計公司的責任到哪裡？

常見的合理安排是：網站端由網頁設計公司負責，對方端由業主協調，雙方技術窗口直接對話。

若期待網頁設計公司代為處理對方端的所有溝通，應該事先說明並反映在報價中。

六、資安面

• 金鑰或憑證怎麼取得與保管？ 絕不可以放在前端程式碼中
• 會傳輸哪些資料？ 若含個人資料，雙方都要符合保護義務
• 連線是否加密？
• 是否需要限制來源位址？

個資的處理原則見會員資料與個資保護。

評估的產出

做完上述確認，你應該能得到：

• 一份具體的串接動作清單
• 對方端的文件與測試環境資訊
• 已知的限制（頻率、欄位、功能）
• 資料對應的落差與處理方式
• 雙方的責任邊界

有了這些，報價才會準確，時程才有依據。

為什麼串接的報價差異這麼大

同樣說「串接 ERP」，報價可能從數萬到數十萬。差異不是廠商亂喊，而是實際的工作量真的差很多。

理解影響因素，才能判斷報價是否合理。

影響成本的七個因素

其中「對方的成熟度」影響最大。串接一個文件完整、有測試環境的知名服務，工作量可能只有串接一套沒有文件的舊系統的幾分之一。

報價應該包含什麼

完整的串接報價通常涵蓋：

1. 可行性評估與規格確認——有些廠商會單獨計價，這是合理的
2. 開發——依動作數量與複雜度
3. 測試——含各種例外情況的測試
4. 上線與轉換——既有資料的初次同步
5. 文件與教學——後台如何操作、出錯如何判斷

其中第三項的工時常被低估。串接的測試比一般功能複雜得多——要測正常流程，也要測對方無回應、回傳錯誤、資料不符等各種狀況。

持續性成本

這是評估時最容易漏掉的：

• 對方服務的費用——月費、按次計費
• 維護費用——對方改版時需要調整
• 監控成本——確認同步是否正常運作

API 串接不是做完就結束的功能。 對方隨時可能改版、調整規格、或停止支援舊版本，屆時網站端必須配合更新，見串接的維護與常見問題。

時程為什麼容易延誤

串接是網站專案中最容易延期的項目，原因幾乎都在網站端以外：

一、申請與開通的時間不可控

對方的審核流程可能需要數週，而且可能來回補件。這段時間完全不在開發端的控制範圍。

建議在專案一開始就啟動申請，與網站開發平行進行。

二、文件與實際不符

很常見的情況：文件寫的欄位與實際回傳的不同、或文件是舊版的。這需要來回測試與確認，時間難以事先估算。

三、對方端的技術窗口回應慢

遇到問題需要對方協助時，回應速度不是你能決定的。

四、需求在過程中才釐清

開始串接後才發現「原來這個欄位對不起來」「原來還要處理退貨的情況」。這是規格沒有先確認清楚的結果。

降低風險的四個做法

1. 先做可行性評估再報價——不要用猜的
2. 提早啟動對方端的申請
3. 分階段進行——先做最核心的一兩個動作，確認可行再擴充
4. 在合約中約定對方端因素造成的時程順延

第四項很重要。如果延誤的原因是對方審核太慢或文件有誤，那不該由開發端承擔罰則。 合約中應有相應的順延機制，見付款方式與延遲處理。

分階段的建議做法

與其一次串接十個動作，不如：

• 第一階段——最有價值的一兩個動作，例如訂單送出
• 觀察一段時間——確認穩定、確認真的省下人力
• 第二階段——再擴充其他動作

好處是：投入可控、風險可控，而且第一階段跑過之後，你會更清楚後續真正需要什麼。

常見的情況是：原本以為需要十個動作，實際運作後發現有三個根本用不到。

一個判斷報價合理性的方法

請廠商說明報價是依據哪些動作、哪些工作項目。願意逐項說明的，通常是真的評估過；只給一個總價而說不出組成的，多半是估的。

報價單的看法見網站架設費用怎麼算。

先決定資料的主從關係

串接設計的第一個問題，也是最重要的問題：同一筆資料，以哪一邊為準？

例如商品價格，網站與 ERP 都有。如果兩邊都能改，改了不同的值，該聽誰的？

常見的三種安排

第一種最單純，也最不容易出錯。 如果 ERP 是庫存的主資料源，那網站後台的庫存欄位就應該設為唯讀，避免有人在網站端改了卻被下次同步覆蓋掉——那會讓人非常困惑。

第二種是實務上最常用的：價格、庫存、料號由 ERP 主導；商品照片、行銷文案、分類由網站主導。

即時同步還是排程同步

實務建議

• 訂單送出用即時——客戶下單後要盡快進入處理流程
• 庫存用高頻排程——例如每十分鐘或每小時，視商品週轉速度而定
• 商品與價格用低頻排程——每日一次通常足夠

不必全部都做成即時。即時同步的成本與風險都較高，只用在真正需要的地方。

庫存同步的特殊考量

庫存是最容易出問題的一項，因為它變動快、而且錯了會直接造成超賣。

兩個實務做法

• 保留安全庫存——ERP 顯示 10 件時，網站只開放 8 件。用緩衝吸收同步延遲
• 下單時再確認一次——結帳前即時向 ERP 查詢，確認確實有貨

第一種簡單但會犧牲部分銷售機會，第二種較準確但增加即時呼叫的次數。可以並用：平時排程同步，結帳時再確認。

超賣的相關處理見金流物流串接的常見問題。

失敗了怎麼辦

這是設計時一定要處理的，因為失敗必然會發生——對方系統維護、網路中斷、資料格式異常。

基本機制

1. 記錄失敗——時間、動作、資料、錯誤訊息
2. 自動重試——但要有次數上限，且間隔逐次拉長，避免持續衝擊對方
3. 超過次數後通知管理者
4. 提供手動重送——後台要能針對單筆重新執行

第四項很實用。沒有手動重送功能，一筆卡住的訂單就只能請廠商進資料庫處理。

不要重複執行

重試機制要注意：同一筆訂單不能被送出兩次。 常見做法是每次傳送帶一個唯一識別碼，讓對方能判斷是否已經處理過。

對帳機制

即使有失敗通知，仍建議定期核對兩邊的資料是否一致。

• 每日核對筆數——網站今天的訂單數與 ERP 收到的是否相同
• 定期核對金額
• 找出只存在於單邊的資料

差異越早發現越好處理。累積一個月的落差，追查起來會非常辛苦。

初次同步的規劃

上線時要把既有資料匯過去，這一步值得單獨規劃：

• 資料量大時要分批，避免一次執行造成負擔或逾時
• 先在測試環境跑一次，確認對應正確
• 保留原始資料的備份
• 驗證筆數與抽查內容

後台要能看到同步狀態

這是驗收時該確認的：

• 最後一次同步的時間與結果
• 失敗紀錄與錯誤訊息
• 單筆資料的同步狀態
• 手動觸發同步的功能

看不到狀態的串接，等於在黑箱中運作——出問題時只能猜。後台的紀錄功能見操作紀錄、備份與資料救回。

串接是會壞掉的功能

一般的網站功能做好就穩定運作，但串接不同——它依賴另一套你無法控制的系統。

對方改版、調整規格、更換憑證、停止支援舊版本，都會讓原本正常的串接突然失效。而且通常不會有人主動通知你。

最常見的六種問題

一、對方改版導致失效

API 規格變更、欄位調整、舊版本停止支援。這是最主要的失效原因。

預防方式：確認申請時留的聯絡信箱有人在看。服務商的改版公告通常寄到那裡，而那個信箱常常是離職員工的。

二、金鑰或憑證過期

多數 API 需要金鑰或憑證來驗證身分，而它們可能有有效期限。過期後串接會全面停止。

預防方式：把到期日納入公司的到期日總表，與網域、主機、SSL 一起管理。

三、超過呼叫頻率限制

流量成長後才浮現的問題。原本每小時幾百次沒問題，訂單量成長後就超限了。

症狀通常是時好時壞——尖峰時段失敗，離峰正常。

四、對方系統維護或故障

短暫的不可用是正常的，重點是網站要能優雅地處理：不要因此讓整個結帳流程當掉，而是記錄下來稍後重試。

五、資料格式的例外

某一筆資料含有特殊字元、欄位超長、或是預期外的空值，造成該筆卡住。

這類問題往往只影響單筆，因此更容易被忽略——直到客戶打電話來問訂單怎麼了。

六、帳號或方案異動

對方服務的方案調整、帳號權限變更、或欠費停用，都會導致串接失效。

監控：不要等客戶告訴你

串接失效最麻煩的是它是靜默的——網站看起來正常，只是資料沒有傳過去。

建議的監控機制

• 失敗時主動通知——寄信或推播給負責人
• 長時間沒有同步也要通知——例如超過一天沒有成功執行過
• 每日的同步摘要——成功幾筆、失敗幾筆
• 後台顯示最後同步時間——一眼就能看出是否停擺

第二項特別重要。只監控「失敗」是不夠的——如果排程根本沒有執行，就不會有失敗紀錄，看起來一切正常。

責任邊界要講清楚

這是實務上最容易產生爭議的地方。建議在合約中明確約定：

第二項最需要事先講清楚。 對方改版不是廠商造成的，但確實需要工時處理。若沒有事先約定，容易演變成「這算不算保固」的爭執。

保固與維護的界線見保固與維護有什麼不同。

出問題時的排查順序

1. 確認範圍——全部失敗還是單筆？從什麼時候開始？
2. 查看失敗紀錄——錯誤訊息通常直接指出原因
3. 確認對方服務是否正常——查看服務狀態公告
4. 確認金鑰與帳號狀態——是否過期、是否欠費
5. 檢查是否收到改版通知——翻一下申請時留的信箱
6. 聯繫廠商，提供上述資訊

前五步自己就能做，而且能大幅縮短處理時間。

準備一份串接清冊

網站串接的服務越多，越需要一份清單：

這份清冊在人員異動時價值最高——否則接手的人根本不知道網站串接了哪些服務。

定期檢查

建議每季確認：

1. 各項串接是否都仍正常運作
2. 是否有金鑰或憑證即將到期
3. 失敗紀錄是否有累積但沒人處理
4. 對方是否有發布改版公告
5. 使用量是否接近方案上限

這幾件事平常不做不會有事，但真的出事時通常已經漏掉一批訂單了。