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