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

# 申請虛擬卡核准

`requestVirtualCard`

提交管理者核准請求以建立虛擬卡。當獲得核准後，Fluz 會依照提交的參數建立該卡片。

## Scopes

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

## Webhook 識別碼

| Field          | Value                   |
| -------------- | ----------------------- |
| `approvalType` | `VIRTUAL_CARD_CREATION` |
| `approvalCode` | `600003`                |

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

## 建立請求

### RequestVirtualCardInput

| Field                | Type                          | Required | Description                                           |
| -------------------- | ----------------------------- | -------- | ----------------------------------------------------- |
| `seatId`             | UUID                          | Yes      | 與申請者關聯的 Seat                                          |
| `offerId`            | UUID                          | Yes      | 虛擬卡優惠 ID。使用 `getVirtualCardOffers` 以列出有效的優惠           |
| `purchaseAmount`     | Float                         | Yes      | 該卡的購買金額                                               |
| `channel`            | SourcePlatformChannel         | Yes      | 請求來源通道（例如 `API`）                                      |
| `fluzpayAmount`      | Float                         | Yes      | 從 Fluz 餘額撥款的金額                                        |
| `spendLimitDuration` | VirtualCardSpendLimitDuration | Yes      | 限制期間：`DAILY`、`WEEKLY`、`MONTHLY`、`ANNUAL` 或 `LIFETIME` |
| `virtualCardPIN`     | String                        | No       | 選用的卡片 PIN                                             |
| `brandLocked`        | Boolean                       | No       | 將卡片鎖定至特定商家品牌                                          |
| `mccId`              | String                        | No       | 商戶分類限制                                                |
| `shareWith`          | \[String]                     | No       | 要分享此卡的使用者 ID                                          |
| `pinAuthToken`       | String                        | No       | 需要時的 PIN 授權權杖                                         |

### 範例 Mutation

```graphql theme={null}
mutation {
  requestVirtualCard(
    input: {
      seatId: "db11ec6c-c371-4184-ab6a-3dfb2c92c4d3"
      offerId: "b23630f6-8d91-43df-84aa-a541e7691197"
      purchaseAmount: 100.00
      channel: API
      fluzpayAmount: 100.00
      spendLimitDuration: MONTHLY
    }
  ) {
    success
    messageId
    error {
      code
      message
    }
  }
}
```

### 範例回應

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

## 核准請求

以 `approvalRequests` 或 `APPROVAL_CREATE` webhook 提供的 `approvalId` 呼叫 `approveApprovalRequest`。需要 `MANAGE_APPROVALS`。

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

在核准後，Fluz 會依照原始請求中的參數建立虛擬卡。

## 拒絕請求

使用 `approvalId` 呼叫 `declineApprovalRequest`。需要 `MANAGE_APPROVALS`。

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

當請求被拒絕時，不會建立任何虛擬卡。