> ## 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 key 的 Basic 认证**（你的 `client_id` 和 `client_secret`），而不是用户访问令牌：

```
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 授权**时，该用户才可访问；且每项操作仅在用户已授予该操作所需的 scope 时才被允许。批量访问从不超出等价的单用户操作范围。

* 断开连接会移除授权，因此断开的用户将不再可访问。
* 如果用户的授权被限定在特定的消费账户上，则该用户的批量结果会自动限制在这些账户内。

## 选择目标用户

每个批量操作都接受一个 `targetSpec`：

| 模式              | 含义                                                 |
| --------------- | -------------------------------------------------- |
| `ALL_CONNECTED` | 当前与你的应用连接的所有用户。                                    |
| `SELECTED`      | 仅你在 `targets` 中列出的、具有相应 `externalReferenceId` 的用户。 |

* 用户通过他们连接时你提供的 `externalReferenceId` 来标识——而不是通过 `accountId`。
* 同步请求最多可指定**100 个目标**。
* 未使用 `externalReferenceId` 连接的用户无法单独选择；他们只能通过 `ALL_CONNECTED` 访问。使用[发现已连接用户](/discover-connected-users)查看谁已连接以及他们授予了哪些 scope。

## 按目标的失败约定

单个目标的失败**不会导致整个请求失败**。每个结果都包含 `success`，且当 `success` 为 `false` 时包含 `error`：

| 代码                          | 含义                                |
| --------------------------- | --------------------------------- |
| `TARGET_NOT_CONNECTED`      | 该 id 不是当前与你的应用连接的用户（未知、已撤销或从未连接）。 |
| `INVALID_TARGET_IDENTIFIER` | 该 id 不是有效的标识符。                    |
| `INSUFFICIENT_SCOPE`        | 用户未授予此操作所需的 scope。                |
| `ACCOUNT_NOT_PERMITTED`     | 用户的授权不允许在所请求的账户上执行此操作。            |

只有在应用级问题时，整个请求才会被拒绝：未启用批量功能、无效请求、超过 100 个目标上限，或当*所有*请求的目标均不可解析时。

每个响应还会汇总 `targetCount`、`successCount` 和 `failureCount`。

## 同步 vs. 异步

* **有界读取为同步**并内联返回：最多 100 个目标，带有每目标限制（例如每个 20 笔交易、90 天时间窗）。本节记录了这三个查询。
* **写入与大规模导出为异步**（即将推出）：你提交作业，轮询其状态，并下载结果。同步读取上的 `hasNextPage`/`totalCount` 会告诉你何时应改用导出，而不是静默截断。

## 本节中的操作

* [发现已连接用户](/discover-connected-users) — `getBulkConnectedOAuthUsers`
* [获取批量余额](/get-bulk-balances) — `getBulkBalances`
* [获取批量交易](/get-bulk-transactions) — `getBulkTransactions`