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

# 請求禮品卡購買核准

`requestGiftCardPurchase`

提交管理者核准請求以購買禮品卡。核准後，Fluz 會使用提交的參數完成購買。

## Scopes

| Action | Scope               |
| ------ | ------------------- |
| 建立請求   | `REQUEST_GIFT_CARD` |
| 列出請求   | `LIST_APPROVALS`    |
| 核准或拒絕  | `MANAGE_APPROVALS`  |

## Webhook 識別碼

| Field          | Value       |
| -------------- | ----------- |
| `approvalType` | `GIFT_CARD` |
| `approvalCode` | `400007`    |

Webhook 事件：`APPROVAL_CREATE`、`APPROVAL_APPROVE`、`APPROVAL_DECLINE`，以及在執行失敗時的 `APPROVAL_HANDLER_ERROR`。

## 建立請求

輸入欄位與直接使用 `purchaseGiftCard` 變更相同。請參考 [Purchase Gift Card](/purchase-gift-card) 以瞭解優惠與資金來源的詳細資訊。

### RequestGiftCardPurchaseInput

| Field                       | Type                  | Required | Description      |
| --------------------------- | --------------------- | -------- | ---------------- |
| `offerId`                   | UUID                  | Yes      | 禮品卡優惠 ID         |
| `purchaseAmount`            | Float                 | Yes      | 購買金額             |
| `channel`                   | SourcePlatformChannel | Yes      | 請求來源管道（例如 `API`） |
| `fluzpayAmount`             | Float                 | No       | 由 Fluz 餘額支付的金額   |
| `bankCardId`                | UUID                  | No       | 銀行卡資金來源          |
| `bankAccountId`             | UUID                  | No       | 銀行帳戶資金來源         |
| `paypalVaultId`             | UUID                  | No       | PayPal 資金來源      |
| `userCashBalanceId`         | UUID                  | No       | 用於資助此次購買的消費帳戶    |
| `seatId`                    | UUID                  | No       | 與此次購買關聯的席位       |
| `exclusiveRateId`           | UUID                  | No       | 專屬費率 ID          |
| `merchantSlug`              | String                | No       | 商家 slug          |
| `gcWarehouseMerchantId`     | UUID                  | No       | 禮品卡倉庫商家 ID       |
| `gcWarehouseUserRewardRate` | Float                 | No       | 倉庫使用者回饋率         |
| `gcWarehouseDiscountRate`   | Float                 | No       | 倉庫折扣率            |
| `memo`                      | String                | No       | 交易備註             |
| `categoryId`                | UUID                  | No       | 交易類別 ID          |

### 範例 Mutation

```graphql theme={null}
mutation {
  requestGiftCardPurchase(
    input: {
      offerId: "ed669305-5e43-40a0-9a25-7a15ed174628"
      purchaseAmount: 25.00
      channel: API
      fluzpayAmount: 25.00
      userCashBalanceId: "b1155504-ad30-4b2f-873d-b8795277b128"
    }
  ) {
    success
    messageId
    error {
      code
      message
    }
  }
}
```

### 範例回應

```json theme={null}
{
  "data": {
    "requestGiftCardPurchase": {
      "success": true,
      "messageId": "1234567890"
    }
  }
}
```

## 核准請求

使用 `approveApprovalRequest` 並提供 `approvalId` 呼叫。需要 `MANAGE_APPROVALS`。

```graphql theme={null}
mutation {
  approveApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
  }
}
```

核准後，Fluz 會購買禮品卡。

## 拒絕請求

使用 `declineApprovalRequest` 並提供 `approvalId` 呼叫。需要 `MANAGE_APPROVALS`。

```graphql theme={null}
mutation {
  declineApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
  }
}
```

當請求被拒絕時，不會購買任何禮品卡。