API 串接的維護與常見問題
串接是會壞掉的功能
一般的網站功能做好就穩定運作，但串接不同——它依賴另一套你無法控制的系統。
對方改版、調整規格、更換憑證、停止支援舊版本，都會讓原本正常的串接突然失效。而且通常不會有人主動通知你。
最常見的六種問題
一、對方改版導致失效
API 規格變更、欄位調整、舊版本停止支援。這是最主要的失效原因。
預防方式：確認申請時留的聯絡信箱有人在看。服務商的改版公告通常寄到那裡，而那個信箱常常是離職員工的。
二、金鑰或憑證過期
多數 API 需要金鑰或憑證來驗證身分，而它們可能有有效期限。過期後串接會全面停止。
預防方式：把到期日納入公司的到期日總表，與網域、主機、SSL 一起管理。
三、超過呼叫頻率限制
流量成長後才浮現的問題。原本每小時幾百次沒問題，訂單量成長後就超限了。
症狀通常是時好時壞——尖峰時段失敗，離峰正常。
四、對方系統維護或故障
短暫的不可用是正常的，重點是網站要能優雅地處理：不要因此讓整個結帳流程當掉，而是記錄下來稍後重試。
五、資料格式的例外
某一筆資料含有特殊字元、欄位超長、或是預期外的空值，造成該筆卡住。
這類問題往往只影響單筆，因此更容易被忽略——直到客戶打電話來問訂單怎麼了。
六、帳號或方案異動
對方服務的方案調整、帳號權限變更、或欠費停用，都會導致串接失效。
監控：不要等客戶告訴你
串接失效最麻煩的是它是靜默的——網站看起來正常，只是資料沒有傳過去。
建議的監控機制
- 失敗時主動通知——寄信或推播給負責人
- 長時間沒有同步也要通知——例如超過一天沒有成功執行過
- 每日的同步摘要——成功幾筆、失敗幾筆
- 後台顯示最後同步時間——一眼就能看出是否停擺
第二項特別重要。只監控「失敗」是不夠的——如果排程根本沒有執行，就不會有失敗紀錄，看起來一切正常。
責任邊界要講清楚
這是實務上最容易產生爭議的地方。建議在合約中明確約定：
| 情況 | 通常的歸屬 |
|---|---|
| 網站端程式錯誤 | 保固範圍內由廠商修正 |
| 對方 API 改版需配合調整 | 通常另計，屬於維護範疇 |
| 對方系統故障 | 非廠商責任，但應協助判斷 |
| 金鑰過期未更新 | 視合約約定的維護範圍 |
| 業主端資料異常 | 業主負責 |
第二項最需要事先講清楚。 對方改版不是廠商造成的，但確實需要工時處理。若沒有事先約定，容易演變成「這算不算保固」的爭執。
保固與維護的界線見保固與維護有什麼不同。
出問題時的排查順序
- 確認範圍——全部失敗還是單筆？從什麼時候開始？
- 查看失敗紀錄——錯誤訊息通常直接指出原因
- 確認對方服務是否正常——查看服務狀態公告
- 確認金鑰與帳號狀態——是否過期、是否欠費
- 檢查是否收到改版通知——翻一下申請時留的信箱
- 聯繫廠商，提供上述資訊
前五步自己就能做，而且能大幅縮短處理時間。
準備一份串接清冊
網站串接的服務越多，越需要一份清單：
| 欄位 | 內容 |
|---|---|
| 服務名稱 | 串接的對象 |
| 用途 | 做什麼 |
| 帳號歸屬 | 登記在誰名下 |
| 聯絡信箱 | 接收改版通知的信箱 |
| 金鑰到期日 | 需要更新的時間 |
| 費用 | 月費或按次計費 |
| 技術窗口 | 出問題找誰 |
這份清冊在人員異動時價值最高——否則接手的人根本不知道網站串接了哪些服務。
定期檢查
建議每季確認：
- 各項串接是否都仍正常運作
- 是否有金鑰或憑證即將到期
- 失敗紀錄是否有累積但沒人處理
- 對方是否有發布改版公告
- 使用量是否接近方案上限
這幾件事平常不做不會有事，但真的出事時通常已經漏掉一批訂單了。