> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 冪等性請求

如果某個 API 呼叫或操作無論執行多少次都產生相同結果，則該操作是冪等的。這可確保重複呼叫不會造成非預期的副作用，從而防止意外的重複請求。

Fluz API 支援冪等性請求，以防止操作被意外重複執行。藉由使用用戶端產生的唯一冪等性金鑰，API 可確保在 10 分鐘期間內，若提供相同的冪等性金鑰，相同的請求不會被處理多次。

## 運作方式

當請求附帶冪等性金鑰時：

* 伺服器會快取初始回應本文及其狀態碼。
* 如果收到具有相同冪等性金鑰與回應碼的重複請求，API 將回傳快取結果，而不會重新執行該操作，特別是在操作內發生錯誤時。此機制藉由在錯誤情境下也回傳一致結果，來避免非預期的重複處理。

## 產生唯一的冪等性金鑰

客戶端需負責建立與更新其冪等性金鑰。為確保唯一性：

* 強烈建議使用 V4 UUID，可透過以下等函式庫產生： [https://github.com/uuidjs/uuid](https://github.com/uuidjs/uuid)
* 做為最佳實務，冪等性金鑰應在一段時間後到期，以避免重複使用並確保請求的唯一性。Fluz 會在 10 分鐘後使每個唯一的冪等性金鑰到期。

### 客戶端需要：

1. 一個產生並儲存新冪等性金鑰的操作
2. 一個依據客戶端到期策略移除舊金鑰的操作

## 必要的操作

並非所有 API 操作都需要冪等性金鑰。為確保資料一致性，Fluz 針對以下關鍵操作要求使用冪等性：

* `purchaseGiftCard`（[在此查看](/purchase-gift-card)）
* `depositCashBalance`（[在此查看](/features/deposit-from-external-accounts)）

對於這些操作，`idempotencyKey` 輸入變數為必填。

## 範例輸入

```json theme={null}
{  
  "idempotencyKey": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "offerId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "amount": 123.45,  
  "balanceAmount": 987.65,  
  "bankAccountId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "bankCardId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "paypalVaultId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "exclusiveRateId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "merchantSlug": "xyz789"  
}
```

<Note>
  Fluz 需要此操作提供冪等性金鑰。
</Note>

## 後續步驟

<CardGroup cols={2}>
  <Card title="購買禮品卡" icon="gift" href="/purchase-gift-card">
    在最常見的資金移動變更作業中，看看冪等性金鑰的實際運作。
  </Card>

  <Card title="地址格式" icon="map-pin" href="/concepts/address-formatting-requirements">
    另一個常見的被拒原因——如何格式化地址以便首次就能通過驗證。
  </Card>
</CardGroup>

<StickyContactSalesBanner />