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

# 创建批量订单

`createVirtualCardBulkOrder` 变更允许你在一次请求中创建多个虚拟卡。

<Info>
  **先决条件：** 具有 `CREATE_VIRTUALCARD` 范围的用户访问令牌，以及一个 `CreateVirtualCardBulkOrderInput` 对象。要查找 `offerId`，请参见 [获取虚拟卡优惠](/features/get-card-offers)。
</Info>

<Note>
  批量订单以异步方式处理。此变更会返回一个 `orderId` 和初始 `orderStatus` 为 `PENDING` —— 轮询 [获取批量订单状态](/features/get-bulk-order-status) 以跟踪完成情况。
</Note>

## 沙盒测试优惠

| Offer ID                               | Program Name                                   | Reward Value |
| :------------------------------------- | :--------------------------------------------- | :----------- |
| `ed669305-5e43-40a0-9a25-7a15ed174628` | Virtual Card                                   | 1.5%         |
| `b23630f6-8d91-43df-84aa-a541e7691197` | Virtual Card - Mastercard Prepaid              | 1.5%         |
| `592c394e-26cc-44ac-a145-a5f81301fe77` | Brand Locked Virtual Card - Mastercard Prepaid | 1.5%         |

## 重要注意事项

* **Offer ID：** `offerId` 会应用于该批量订单中创建的所有卡片。
* **资金来源：** 你可以使用 Fluz 余额或已关联的银行账户为你的虚拟卡提供资金。
  * 如果选择银行账户作为 `primaryFundingSource`，必须提供 `bankAccountId`。
* **消费限额：** 你设置的 `spendLimit` 必须遵守所选 `spendLimitDuration` 对应项目定义的消费限额。若超出将会报错。
* **数量：** `orderItems` 数组中的每一项都包含 `quantity`，可高效创建具有相同配置的多张卡片。

## 参数

* `input` (`CreateVirtualCardBulkOrderInput!`): 包含新虚拟卡批量订单详细信息的输入对象。

## CreateVirtualCardBulkOrderInput 字段

| Field        | Type                                      | Description                                              | Required |
| :----------- | :---------------------------------------- | :------------------------------------------------------- | :------- |
| `offerId`    | `UUID!`                                   | 用于该批量订单中所有卡片的 Offer ID。使用 getVirtualCardOffers 获取有效优惠列表。 | Yes      |
| `orderItems` | `[CreateVirtualCardBulkOrderItemInput!]!` | 一个对象数组，每个对象定义要创建的一组虚拟卡。                                  | Yes      |

### CreateVirtualCardBulkOrderItemInput 字段

| Field                  | Type                            | Description                                               | Required |
| :--------------------- | :------------------------------ | :-------------------------------------------------------- | :------- |
| `quantity`             | `Int!`                          | 使用该特定配置要创建的虚拟卡数量。                                         | Yes      |
| `spendLimit`           | `Float!`                        | 每张卡可被扣款的最大金额。你只会为实际使用的金额付费。                               | Yes      |
| `spendLimitDuration`   | `VirtualCardSpendLimitDuration` | 卡片限额的时长类型。默认是 `LIFETIME`。                                 | No       |
| `lockDate`             | `String`                        | 卡片将被锁定的日期。默认是自创建起 47 个月。格式：yyyy-mm-dd                     | No       |
| `lockCardNextUse`      | `Boolean`                       | 设置在卡片下次使用后将其锁定。默认值为 `false`。                              | No       |
| `cardNickname`         | `String`                        | 卡片昵称。                                                     | No       |
| `primaryFundingSource` | `VirtualCardFundingSource`      | 虚拟卡的主要资金来源。默认是 `FLUZ_BALANCE`。                            | No       |
| `bankAccountId`        | `UUID`                          | 银行账户的唯一标识符。当 `primaryFundingSource` 为 `BANK_ACCOUNT` 时必填。 | No       |

## cURL 示例

```bash theme={null}
curl -X POST \
  https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_USER_ACCESS_TOKEN' \
  -d '{
    "query": "mutation CreateVirtualCardBulkOrder { createVirtualCardBulkOrder( input: { offerId: \"592c394e-26cc-44ac-a145-a5f81301fe77\", orderItems: [ { quantity: 3, spendLimit: 100, spendLimitDuration: DAILY, lockCardNextUse: true, cardNickname: \"Test nickname\", primaryFundingSource: FLUZ_BALANCE }, { quantity: 1, spendLimit: 200, spendLimitDuration: WEEKLY, lockCardNextUse: false, lockDate: \"2030-10-10\", cardNickname: \"Test nickname 2\", primaryFundingSource: BANK_ACCOUNT, bankAccountId: \"7f60cb5d-683f-4181-9194-408ea92d6248\" } ] } ) { orderId orderStatus } }"
  }'
```

## 示例变更

```graphql theme={null}
mutation CreateVirtualCardBulkOrder {
    createVirtualCardBulkOrder(
        input: {
            offerId: "592c394e-26cc-44ac-a145-a5f81301fe77"
            orderItems: [
                {
                    quantity: 3
                    spendLimit: 100
                    spendLimitDuration: DAILY
                    lockCardNextUse: true
                    cardNickname: "Test nickname"
                    primaryFundingSource: FLUZ_BALANCE
                }
                {
                    quantity: 1
                    spendLimit: 200
                    spendLimitDuration: WEEKLY
                    lockCardNextUse: false
                    lockDate: "2030-10-10"
                    cardNickname: "Test nickname 2"
                    primaryFundingSource: BANK_ACCOUNT
                    bankAccountId: "7f60cb5d-683f-4181-9194-408ea92d6248"
                }
            ]
        }
    ) {
        orderId
        orderStatus
    }
}
```

## 示例响应

```json theme={null}
{
  "data": {
    "createVirtualCardBulkOrder": {
      "orderId": "MTFkYjIxNTYtNTEwOS00ODNmLTkwMTYtYjA5N2E2NTEyMjU5fDIzMjIxODRhLTEzMjgtNDkwYy05Mzc1LTZlOWM4MWIwMjkzZA==",
      "orderStatus": "PENDING",
    }
  }
}
```

## 响应字段

| Field         | Type                          | Description                                               |
| ------------- | ----------------------------- | --------------------------------------------------------- |
| `orderId`     | `UUID`                        | 批量创建订单的唯一标识符。将其传递给 `getVirtualCardBulkOrderStatus` 以跟踪进度。 |
| `orderStatus` | `VirtualCardBulkOrderStatus!` | 批量订单状态（例如，`COMPLETED`、`PENDING`、`FAILED`）。                |

## 后续步骤

<Card title="获取批量订单状态" icon="list-checks" horizontal href="/features/get-bulk-order-status">
  轮询该 `orderId` 以跟踪处理进度，并在卡片签发后获取它们。
</Card>