> ## 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` 变更允许你使用礼品卡代码，将 Fluz 礼品卡兑换到已认证用户的账户中。

兑换成功会将金额记入用户的**礼品卡余额**（`giftCardCashBalance`）。

此变更需要 `MAKE_DEPOSIT` 权限范围。

***

### 参数

* **`input`**（`RedeemFluzGiftCardInput!`）：包含幂等键与礼品卡代码的输入对象。

***

### RedeemFluzGiftCardInput 字段

| 字段               | 类型        | 描述                      | 必填 |
| ---------------- | --------- | ----------------------- | -- |
| `idempotencyKey` | `UUID!`   | 客户端生成的唯一键，确保请求仅被处理一次。   | 是  |
| `code`           | `String!` | Fluz 礼品卡代码。会自动去除首尾空白字符。 | 是  |

***

### 响应

返回 `DepositCashBalanceResponse`，包括：

* **`cashBalanceDeposits`** — 为本次兑换创建的存入记录
* **`balances`** — 兑换后的用户余额更新

> 兑换的金额会计入 `balances.giftCardCashBalance`（而非 `cashBalance`）。

***

### 示例变更

```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`   | 一般性失败（例如功能访问、内部错误）。              |