> ## 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 个已连接用户** 的现金余额，每个目标一条结果。

## 要求

* `Authorization: Basic <API_KEY>`（你的应用程序 API 密钥）
* 你的应用已启用 **批量 API 功能**
* 每个目标用户的授权中包含 `LIST_PAYMENT` 权限范围

失败将按目标单独报告，永远不会导致整个请求失败。参见 [批量 API 概览](/bulk-api)，了解定位模型和错误代码。

## 查询

```graphql theme={null}
query GetBulkBalances($targetSpec: BulkTargetSpecInput!) {
  getBulkBalances(targetSpec: $targetSpec) {
    targetCount
    successCount
    failureCount
    results {
      externalReferenceId
      accountId
      success
      error { code message }
      balances {
        userCashBalanceId
        nickname
        status
        totalCashBalance
        availableCashBalance
        lifetimeCashBalance
        createdAt
      }
    }
  }
}
```

### 变量 — 指定用户

```json theme={null}
{
  "targetSpec": { "mode": "SELECTED", "targets": ["your-user-001", "your-user-002"] }
}
```

### 变量 — 所有已连接用户

```json theme={null}
{
  "targetSpec": { "mode": "ALL_CONNECTED" }
}
```

## 响应

```json theme={null}
{
  "data": {
    "getBulkBalances": {
      "targetCount": 2,
      "successCount": 1,
      "failureCount": 1,
      "results": [
        {
          "externalReferenceId": "your-user-001",
          "accountId": "8f3c…",
          "success": true,
          "error": null,
          "balances": [
            {
              "userCashBalanceId": "ucb-1",
              "nickname": "Main account",
              "status": "ACTIVE",
              "totalCashBalance": "125.50",
              "availableCashBalance": "100.00",
              "lifetimeCashBalance": "500.00",
              "createdAt": "2026-01-01T00:00:00.000Z"
            }
          ]
        },
        {
          "externalReferenceId": "your-user-002",
          "accountId": "a90d…",
          "success": false,
          "error": {
            "code": "INSUFFICIENT_SCOPE",
            "message": "The user has not granted the scopes this operation requires. Missing scopes: LIST_PAYMENT."
          },
          "balances": null
        }
      ]
    }
  }
}
```

## 参数

| 参数                   | 类型                | 描述                                                                                        |
| -------------------- | ----------------- | ----------------------------------------------------------------------------------------- |
| `targetSpec.mode`    | `BulkTargetMode!` | `ALL_CONNECTED` 或 `SELECTED`。                                                             |
| `targetSpec.targets` | `[String!]`       | 要定位的 `externalReferenceId`。在 `SELECTED` 时必填；在 `ALL_CONNECTED` 时忽略。会去重；结果顺序遵循该列表。最多 100 个。 |

## 响应字段

| 字段                                              | 描述                                               |
| ----------------------------------------------- | ------------------------------------------------ |
| `results[].success`                             | 是否为该目标返回了余额。                                     |
| `results[].error`                               | 当 `success` 为 `false` 时存在。错误代码见 [概览](/bulk-api)。 |
| `results[].balances`                            | 用户的现金余额。当授权限定到特定消费账户时，仅返回被允许的消费账户。               |
| `targetCount` / `successCount` / `failureCount` | 请求级别摘要。                                          |

<Note>
  授权限定到特定消费账户的目标将仅返回这些余额——自动生效，无需额外参数。
</Note>