> ## 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.

# 兌換 Fluz 禮品卡

`redeemFluzGiftCard` mutation 可讓你使用禮品卡代碼，將 Fluz 禮品卡兌換到已驗證使用者的帳戶。

兌換成功會將金額存入使用者的**禮品卡餘額**（`giftCardCashBalance`）。

此 mutation 需要 `MAKE_DEPOSIT` 範圍。

***

### 參數

* **`input`**（`RedeemFluzGiftCardInput!`）：包含冪等鍵與禮品卡代碼的輸入物件。

***

### RedeemFluzGiftCardInput 欄位

| 欄位               | 型別        | 說明                    | 必填 |
| ---------------- | --------- | --------------------- | -- |
| `idempotencyKey` | `UUID!`   | 用戶端產生的唯一鍵，確保請求只被處理一次。 | 是  |
| `code`           | `String!` | Fluz 禮品卡代碼。前後空白會自動去除。 | 是  |

***

### 回應

回傳 `DepositCashBalanceResponse`，包含：

* **`cashBalanceDeposits`** — 本次兌換所建立的存入紀錄
* **`balances`** — 兌換後更新的使用者餘額

> 兌換的金額會存入 `balances.giftCardCashBalance`（而非 `cashBalance`）。

***

### 範例 Mutation

```graphql theme={null}
mutation RedeemGC($input: RedeemFluzGiftCardInput!) {
  redeemFluzGiftCard(input: $input) {
    cashBalanceDeposits {
      cashBalanceDepositId
      depositDisplayId
      depositAmount
      depositFee
      status
      cashBalanceDepositType
      transactionDate
      clearedDate
      cashBalanceSettlements {
        cashBalanceSettlementId
        availabilityType
        status
      }
    }
    balances {
      cashBalance {
        availableBalance
        totalBalance
        pendingBalance
        lifetimeBalance
      }
      giftCardCashBalance {
        availableBalance
        totalBalance
        lifetimeBalance
      }
      rewardsBalance {
        availableBalance
        totalBalance
        lifetimeBalance
      }
    }
  }
}
```

***

### 變數

```json theme={null}
{
  "input": {
    "idempotencyKey": "ee940ccc-2d24-4e1f-8c81-1a3a8b59fa01",
    "code": "FLUZ-GC-CODE-EXAMPLE"
  }
}
```

***

### cURL 範例

```bash theme={null}
curl -X POST \
  https://transactional-graph-service.fluzapp.com/api/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_USER_ACCESS_TOKEN' \
  -d '{
    "query": "mutation RedeemGC($input: RedeemFluzGiftCardInput!) { redeemFluzGiftCard(input: $input) { cashBalanceDeposits { cashBalanceDepositId depositDisplayId depositAmount depositFee status cashBalanceDepositType transactionDate clearedDate cashBalanceSettlements { cashBalanceSettlementId availabilityType status } } balances { cashBalance { availableBalance totalBalance pendingBalance lifetimeBalance } giftCardCashBalance { availableBalance totalBalance lifetimeBalance } rewardsBalance { availableBalance totalBalance lifetimeBalance } } } }",
    "variables": {
      "input": {
        "idempotencyKey": "ee940ccc-2d24-4e1f-8c81-1a3a8b59fa01",
        "code": "FLUZ-GC-CODE-EXAMPLE"
      }
    }
  }'
```

***

### 行為

* **餘額目的地** — 資金會存入 `giftCardCashBalance`。
* **冪等性** — 針對相同的 `idempotencyKey`，在處理中的重複請求會被拒絕。
* **空白處理** — `code` 的前後空白會自動去除。
* **手續費** — 任何啟用費用會反映在 `depositFee` 中。
* **清算** — 兌換為**即時**（`INSTANT`、`AVAILABLE`）。

***

### 錯誤

| 代碼         | 說明                                |
| ---------- | --------------------------------- |
| `ARG-XXXX` | 遺漏或無效的 `idempotencyKey` 或 `code`。 |
| `GC-0003`  | 無效、未啟用或已被兌換的禮品卡。                  |
| `G-0409`   | 相同 `idempotencyKey` 的重複請求正在進行中。   |
| `G-0004`   | 一般性失敗（例如功能存取、內部錯誤）。               |