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

# 批次 API

> 在一次呼叫中讀取並對許多已連結的 Fluz 使用者執行動作，而不是一次處理一個使用者權杖。

批次 API 讓你的應用程式能在**一次呼叫中跨許多已連結的 Fluz 使用者執行動作**，而不必一次又一次以單一使用者權杖迴圈呼叫。此功能是為需要代表連結至你應用程式的使用者讀取資料或（即將推出）移轉資金的 OAuth 應用程式開發者所打造。

<Note>
  這與虛擬卡片下的「Create Virtual Card Bulk Order」操作不同，後者會為「單一」帳戶建立多張卡片。批次 API 則是跨「你已連結的使用者」運作。
</Note>

## 誰可以使用

批次 API 以應用程式層級控管。你的應用程式必須由 Fluz 啟用**批次 API 能力**——請與我們聯繫以申請存取權。非批次啟用的應用程式所發出的呼叫將以 `BulkApiAccessDenied` 被拒絕。

## 驗證

所有批次 API 呼叫均使用**以你的應用程式 API 金鑰**（你的 `client_id` 與 `client_secret`）進行的 Basic 驗證，而非使用者存取權杖：

```
Authorization: Basic <API_KEY>
```

端點（staging）：

```
https://transactional-graph.staging.fluzapp.com/api/v1/graphql
```

端點（production）：

```
https://transactional-graph.fluzapp.com/api/v1/graphql
```

## 授權來自既有連線

批次 API 不會建立新的同意介面。只有在使用者對你的應用程式具有**有效的 OAuth 授權**時，該使用者才可被觸及，且每個操作都僅在使用者已授與該操作所需的範圍（scopes）時才被允許。批次存取絕不會比等價的單一使用者操作更寬鬆。

* 中斷連線會移除授權，因此中斷連線的使用者將不再可被觸及。
* 如果使用者的授權僅限於特定的消費帳戶，該使用者的批次結果將自動限制於那些帳戶。

## 選取目標使用者

每個批次操作都需要 `targetSpec`：

| Mode            | Meaning                                              |
| --------------- | ---------------------------------------------------- |
| `ALL_CONNECTED` | 目前所有已連結至你應用程式的使用者。                                   |
| `SELECTED`      | 僅限你在 `targets` 中列出的、其 `externalReferenceId` 所對應的使用者。 |

* 以你在連結時提供的 `externalReferenceId` 指定使用者——不是以 `accountId`。
* 同步請求最多可指定**100 個目標**。
* 未以 `externalReferenceId` 連結的使用者無法被個別選取；只能透過 `ALL_CONNECTED` 觸及。使用 [Discover Connected Users](/discover-connected-users) 來查看誰已連結以及他們授與了哪些範圍。

## 每個目標的失敗合約

單一目標的失敗**不會使整個請求失敗**。每個結果都會帶有 `success`，且當 `success` 為 `false` 時會包含 `error`：

| Code                        | Meaning                               |
| --------------------------- | ------------------------------------- |
| `TARGET_NOT_CONNECTED`      | 此 ID 並非目前已連結至你應用程式的使用者（未知、已撤銷、或從未連結）。 |
| `INVALID_TARGET_IDENTIFIER` | 此 ID 不是有效的識別碼。                        |
| `INSUFFICIENT_SCOPE`        | 使用者未授與此操作所需的範圍。                       |
| `ACCOUNT_NOT_PERMITTED`     | 使用者的授權不允許在請求的帳戶上執行此操作。                |

整個請求只會因應用程式層級的問題而被拒絕：未啟用批次、無效的請求、超過 100 個目標上限，或當*所有*請求的目標都無法解析時。

每個回應也會彙總 `targetCount`、`successCount` 與 `failureCount`。

## 同步與非同步

* **受限範圍的讀取為同步**，並在回應中直接提供：最多 100 個目標，且具每個目標的限制（例如各 20 筆交易、90 天期間）。本章節文件化的即是這三個查詢。
* **寫入與大型匯出為非同步**（即將推出）：你提交作業、輪詢其狀態，並下載結果。同步讀取中的 `hasNextPage`/`totalCount` 會告訴你何時該改用匯出，而不是默默截斷。

## 本節中的操作

* [探索已連結的使用者](/discover-connected-users) — `getBulkConnectedOAuthUsers`
* [取得批次餘額](/get-bulk-balances) — `getBulkBalances`
* [取得批次交易](/get-bulk-transactions) — `getBulkTransactions`