> ## 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.
# 一次發卡 100 張
> 建立大量虛擬卡訂單、輪詢至完成，並處理部分失敗 — 大規模程式化發卡模式。
本快速入門示範如何在一個請求中發行 100 張虛擬卡。你將建立一筆非同步的大量訂單、在卡片建立過程中輪詢狀態，並擷取完整卡片詳細資料 — 無論你要發 10 張或 10,000 張，流程都相同。
**先決條件**
* 一個**具有測試環境應用程式的 Fluz 帳戶** — 任一快速入門的步驟 1–2，或參見[準備你的帳戶](/get-started/prepare-accounts)與 [API 憑證](/get-started/api-credentials)。
* 具有 **`CREATE_VIRTUALCARD`** 權限範圍的權杖。
* 有足夠可用餘額以支付訂單 — 100 張卡 × 你設定的消費上限。每次變更操作都需要唯一的 `idempotencyKey` — 參見[冪等性](/concepts/idempotency)。
## 完整流程
一次 `createVirtualCardBulkOrder` 呼叫可建立全部 100 張卡。`orderItems` 中的每個項目都是一個卡片設定並包含 `quantity` — 以下為 100 張相同的單次使用撥付款卡：
```graphql Mutation theme={null}
mutation createVirtualCardBulkOrder($input: CreateVirtualCardBulkOrderInput!) {
createVirtualCardBulkOrder(input: $input) {
orderId
orderStatus
}
}
```
```json Variables theme={null}
{
"input": {
"idempotencyKey": "9f2a1c30-7b8d-4e1f-a6c2-5d3e8f901b2c",
"offerId": "592c394e-26cc-44ac-a145-a5f81301fe77",
"orderItems": [
{
"quantity": 100,
"spendLimit": 25.00,
"lockCardNextUse": true,
"cardNickname": "July payout batch",
"primaryFundingSource": "FLUZ_BALANCE"
}
]
}
}
```
```json Response theme={null}
{
"data": {
"createVirtualCardBulkOrder": {
"orderId": "ZTBhYTg2YmQt...",
"orderStatus": "PENDING"
}
}
}
```
`offerId` 會套用到訂單中的**每一張**卡；如需混合設定，可新增更多 `orderItems` 項目（例如，80 張 × $25 的單次使用，加上 20 張 × $100 的每月卡）。`lockCardNextUse: true` 會讓每張卡於第一次扣款後自我失效 — 這是標準的撥付模式。
大量訂單為**非同步** — 回應只會提供 `orderId` 與 `PENDING`，不會直接回傳卡片。請保存 `orderId`；它是後續所有操作的依據。
使用 `getVirtualCardBulkOrderStatus` 追蹤進度。當訂單仍為 `PENDING` 時，卡片會逐步產生：
```graphql Query theme={null}
query getVirtualCardBulkOrderStatus($input: GetVirtualCardBulkOrderStatusInput!) {
getVirtualCardBulkOrderStatus(input: $input) {
orderId
orderStatus
successfulCardCreations
failedCardCreations
totalCards
virtualCards {
virtualCardId
cardNumber
expiryMMYY
cvv
cardHolderName
}
}
}
```
```json Variables theme={null}
{ "input": { "orderId": "" } }
```
以退避策略進行輪詢，直到 `orderStatus` 變為 `COMPLETED`（或 `FAILED`）— 在待處理期間，`successfulCardCreations` 會逐步接近 `totalCards`，而 `virtualCards` 也會逐步填入。
回應中包含以純文字呈現的**完整卡號（PAN）、CVV 與到期日**。請視為敏感持卡人資料：僅透過 TLS 傳輸、切勿記錄日誌、且只提供給授權使用者檢視。
大量訂單可能部分成功：在完成的訂單上出現 `successfulCardCreations: 98, failedCardCreations: 2`，代表有 98 張有效可用的卡，另有 2 張需要重試。請比較這些計數與 `totalCards` 以核對，然後只重新發行短缺的卡 — 並使用**新的** `idempotencyKey`，因為這是新訂單：
```json theme={null}
{
"input": {
"idempotencyKey": "",
"offerId": "592c394e-26cc-44ac-a145-a5f81301fe77",
"orderItems": [{ "quantity": 2, "spendLimit": 25.00, "lockCardNextUse": true }]
}
}
```
持續失敗通常與方案限制或資金有關 — 請檢查[虛擬卡錯誤代碼](/features/virtual-card-error-codes)以及你的可用餘額。
## 大功告成 🎉
只需一個請求就能取得一百張已設定好的卡，再配合即可用於正式環境的輪詢迴圈。接下來：
監控整批的消費 — 每次查詢最多 10 張卡，或依日期查詢整個帳戶。
要發送給組織外的人嗎？託管的領取連結可為你處理導入流程。
**想了解更多？** 歡迎聯絡我們： [support@fluz.app](mailto:support@fluz.app) 與專家對談或預約示範。