> ## 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 } }"
  }'
```

## 範例 mutation

```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>