狀態 

冪等性鑰匙支援目前為部分支援。已選取的內部重試 mutations（例如訂單帳單重試及退款帳單重試流程）已接受冪等性鑰匙並使用該鑰匙來刪除重複的下游支付處理器呼叫。Zonos Graph 上尚未有跨所有面向客戶的建立 mutations 的標準化 idempotencyKey 參數；該功能已納入規劃。在推出前，請使用下列模式來保持 mutations 安全可重試。

預設安全的 mutations 

某些 mutations 本身就是冪等的，因為它們會按照您提供的穩定識別碼進行更新插入。當您使用相同的輸入呼叫這些 mutations 時，結果是相同的——不存在建立重複項的風險。

• 接受唯一商戶提供識別碼的 mutations（例如訂單 externalId）將在重複呼叫時返回現有記錄，而不是建立新記錄。
• 唯讀操作（queries）始終安全可重試。

當您可以將自己的穩定識別碼連接到正在建立的資源時，優先選擇該途徑。

非本身冪等的 mutations 的模式 

對於建立沒有商戶提供鑰匙的資源的 mutations，將其視為來自您端的最多一次：

1. 在傳送前持久化請求。 在進行網路呼叫之前，將一列寫入您自己的資料庫（狀態為 pending）。
2. 傳送 mutation。 成功時，根據您待提交列記錄返回的資源 id（狀態 committed）。
3. 在網路錯誤時，請勿盲目重試。 查詢 Zonos Graph 以確定資源是否已建立（例如，透過列出過去幾分鐘內為您的帳戶建立的資源，或透過查詢您可以相關聯的相關資源）。僅在確認資源不存在時重試。
4. 在您自己的資料庫中使用唯一約束，涉及代表請求的任何業務鑰匙，以確保來自您自己應用程式的重複重試不會重複提交。

Webhook 傳遞至少一次 

當您使用 Zonos webhooks 時，設計處理器應為冪等的——同一事件可能會被傳遞多次。按事件 id 進行刪除重複。請參閱 Webhooks 中的事件 id 欄位。

平台發展方向 

基礎平台已在生產中執行帳單重試的冪等性鑰匙流程：鑰匙會定義重試嘗試的範圍並防止重複的支付處理器呼叫。我們正致力於將相同模式公開為面向客戶的建立 mutations 上的選用 idempotencyKey 參數。提供時，Graph 將在保留期內的任何後續使用相同鑰匙的呼叫中返回原始回應。當該功能正式全面推出時，本頁面將會更新。

如果面向客戶的 mutations 上的標準冪等性鑰匙阻礙您的整合，聯繫支援。