如何停用舊版合作夥伴 API，而不令客戶系統中斷

找出流量背後的客戶

停用舊版 API 應有具體原因，例如維護負擔或阻礙必要改動，而不是因為新版路徑看起來較整齊。先列出舊版與新版的端點、方法、請求欄位、回應欄位、錯誤處理及身分驗證，再把存取紀錄與實際合作機構連結。單看呼叫次數，可能漏掉每月只執行一次的對帳程式。為每項整合記下負責人、技術聯絡人、支援的業務流程及正常執行週期。整理紀錄時仍須遵守私隱與保存規則；盤點所需的是客戶及端點使用模式，並非憑證或完整客戶資料。

把可自行升級的客戶，與須依靠供應商、加盟商或已離職員工維護系統的客戶分開處理。請各聯絡人確認由誰部署及測試。低流量端點可能承載付款對帳、庫存更新或定期取檔等重要工作，不能只按使用量排序。無法辨認的呼叫應列為待查資料，不能直接當成無人使用。若識別不足，可在不記錄秘密的前提下改善客戶身分紀錄，並請已知合作夥伴確認其測試及正式環境。這些盤點結果有助訂出支援安排和合理遷移期，但本身不足以批准停機。保留有日期的舊版使用基線，日後才能以相同口徑檢查進度。

以小型訂單 API 為例，假設一名夥伴每分鐘提交訂單，一名每月下載結算檔，另一名只有測試環境；這只是說明情境，並非 Astera 客戶實況。第一名須測試吞吐量及重複訂單處理，第二名須在新版完成至少一次完整結算週期，第三名則須確認正式憑證或排程工作沒有繼續使用舊路徑。只發一次公告，或只看舊版總流量下降，都會掩蓋這些差異。遷移紀錄應以業務結果是否完成為準，而非只記錄 HTTP 回應成功。

讓新版成為可測試的明確介面

遷移指南要逐一對照舊操作與新操作，說明必填欄位、預設值、識別碼、排序、分頁、身分驗證、驗證規則及錯誤回應有何改變。沒有直接替代的欄位，或需要客戶修改本身資料模型的地方，必須明確指出。提供正常請求及客戶必須處理的失敗例子。單有版本編號並不足夠：整合程式即使收到成功回應，也可能悄悄遺失開發票所需欄位。可行時讓新舊版並行一段經評估的時間，同時清楚界定相容範圍，避免雙方誤以為舊版會繼續加入所有新功能。

提供與正式環境清楚區分資料及限制的測試帳戶。與客戶商定驗收證據：具代表性的新增、讀取及修改流程、預期錯誤處理、適用時的重複請求重播，以及業務紀錄比對。也要涵蓋空結果、第二頁以後的分頁、憑證到期及上游延誤。若合作夥伴只在測試程式改了網址，仍未證明夜間匯入或人工異常處理可運作。為每項整合指定驗收負責人，保存測試結果時避免在共用工單暴露真實個人資料。回退方案要說明可切回哪個版本，以及哪些紀錄需要重新對帳。

溝通應分階段，而非只發一次警告。把變更對照及建議日期交給業務負責人與開發人員，請他們確認收悉，安排測試時段，再向仍使用舊版的個別客戶回報其情況。讓客戶提出真正的阻礙，並指定一名決策負責人在證據充分時延長期限。若合約通知期或關鍵整合問題尚未釐清，不應保證停用日期絕不變動；但無限期保留舊版亦會形成無上限的支援負擔。先訂出選日期的標準，任何變動都公開通知，停用後仍保留遷移文件供排查及稽核。

正確使用生命週期訊號

RFC 9745 定義的 Deprecation 回應標頭，用來告知使用者資源已經或即將棄用；加入標頭本身不會改變資源行為。deprecation 連結可指向供人閱讀的遷移文件。RFC 8594 的 Sunset 標頭用途不同，表示資源預期何時可能停止回應，其值使用 HTTP 日期格式。該時間只是提示，不能保證資源一定運作至最後一刻，也不保證屆時立即失效。這些機器可讀訊號有幫助，但客戶程式可能根本不讀取；直接聯絡、文件和變更通知仍不可少。公告日期、標頭值及文件必須一致。

不要把教學例子的時間戳直接抄到正式環境。訂日期前，核對合約通知、客戶部署週期、支援人手及業務旺季；在人類可讀通知中寫明時區，並驗證系統輸出的標頭語法。測試所有受影響的回應路徑，包括客戶可能首先察覺問題的錯誤回應。舊路徑停用後究竟回傳有文件說明的錯誤、在安全情況下重新導向，還是其他明確回應，都須自行設計；Sunset 規格不會代你決定。對可能改動資料的請求，重新導向可能令客戶程式出現意外行為，不能把它直接當成遷移方案。

停用舊版是一項正式發佈工作，不只是日曆上的日期。更改正式環境前，將近期舊版呼叫與遷移紀錄比對，檢查未分配的呼叫者，並確認關鍵客戶已在新版完成相應業務週期。切換期間按客戶及操作監察錯誤率和實際結果，安排人手調查失敗。其後按驗收時相同的業務定義，核對訂單或結算總額等重要紀錄。如漏掉必要客戶，事故負責人須依預先商定的方案，選擇短暫恢復、針對性例外或協助遷移，並記錄決定及通知內容。證據確認依賴已結束後，才移除過時程式及存取權。

最後可安排一次以陌生合作夥伴角度進行的演練：只憑已公開的遷移指南及測試憑證，完成整個業務流程，包括失敗請求、重複請求及日終對帳。記下哪些步驟仍依賴內部開發人員沒有寫出的知識。若文件未解釋缺少欄位是未知、被省略還是已移除，客戶可能套用危險的預設值。請沒有設計 API 的支援同事按指南回答一條模擬遷移查詢，再修正文件。同時檢查可觀察性：客服能否憑安全的請求識別碼找到失敗呼叫，而毋須看到秘密？客戶能否知道是哪個版本處理回應？清楚寫出並行期間的升級通道及缺陷責任，讓停用計劃成為合作夥伴真正可執行的服務轉移。

最後決定如期停用還是延期時，要有明確證據：哪些正式環境夥伴確認收到通知、哪些通過新版測試、最近觀察時段哪些仍呼叫舊版、每項例外由誰負責及何時到期。例外應限定受影響的操作與客戶，不能預設整個舊版無限期開放。若停用日期改變，應同步更新公開指南、機器可讀訊號及個別客戶通知。切換後仍須保留一段合適的監察，以發現稍後才啟動的每月或每季工作。舊端點每日流量少，單憑這點從不足以證明可安全移除。留下決策紀錄，企業才能解釋停用時機，以及漏掉依賴時如何處理。