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

# 取得消費帳戶

在建立消費帳戶後，您可以透過以下查詢來存取：

1. `getUserCashBalances` - 取得您所有消費帳戶的清單。
2. `getUserCashBalanceById` - 根據其 id 值取得特定消費帳戶。

<Warning>
  **需要授權**

  此變更需要 `LIST_PAYMENT` 範圍。嘗試在內部轉移資金前，請確保您的存取權杖已被授予此範圍。
</Warning>

## 消費帳戶詳情

`UserCashBalanceDetails` 物件包含有關消費帳戶的重要資訊。

| 欄位名稱                 | 型別                     | 說明                     |
| :------------------- | :--------------------- | :--------------------- |
| userCashBalanceId    | UUID!                  | 現金餘額帳戶的唯一識別碼           |
| totalCashBalance     | String!                | 帳戶中的總現金餘額（起始為 0）       |
| availableCashBalance | String!                | 可立即使用的現金餘額（起始為 0）      |
| lifetimeCashBalance  | String!                | 有史以來所有存入資金的累計總額（起始為 0） |
| nickname             | String                 | 指派給帳戶的自訂名稱             |
| status               | UserCashBalanceStatus! | 帳戶目前狀態（ACTIVE, CLOSED） |
| isDefault            | Boolean!               | 此消費帳戶是否為預設帳戶           |
| createdAt            | DateTime!              | 建立帳戶的時間戳記              |
| updatedAt            | DateTime!              | 更新帳戶的時間戳記              |

## 取得消費帳戶清單

若要取得在您帳戶下建立的消費帳戶清單，請使用 `getUserCashBalances` 查詢。此呼叫會回傳包含基本資訊的消費帳戶清單，包括 `userCashBalanceId`。您需要此 ID 才能透過 `getuserCashBalanceById` 取得特定消費帳戶。

### 變數

| 欄位       | 型別                         | 必填 | 說明                          |
| -------- | -------------------------- | -- | --------------------------- |
| filter   | UserCashBalanceFilterInput | 否  | 消費帳戶的篩選條件                   |
| paginate | OffsetInput                | 否  | 分頁參數（預設：limit=20, offset=0） |

### 範例請求

```graphql theme={null}
query GetUserCashBalances(
  $filter: UserCashBalanceFilterInput,
  $paginate: OffsetInput,
) {
  getUserCashBalances(
    filter: $filter
    paginate: $paginate
  ) {
    userCashBalances {
        userCashBalanceId
        totalCashBalance
        availableCashBalance
        lifetimeCashBalance
        nickname
        status
        isDefault
        createdAt
        updatedAt
    }
    totalCount
    hasNextPage
  }
}
```

<Note>
  請注意，由於速率限制，您可能需要進行分頁並多次呼叫消費帳戶清單。
</Note>

### 範例回應

回應將包含消費帳戶的清單

```json JSON theme={null}
{
    "data": {
        "getUserCashBalances": {
            "userCashBalances": [
                {
                    "userCashBalanceId": "c115604e-5d47-473c-a955-41a820cdcaf8",
                    "totalCashBalance": "0.00",
                    "availableCashBalance": "0.00",
                    "lifetimeCashBalance": "768.00",
                    "nickname": "Virtual Prepaid Account",
                    "status": "ACTIVE",
                    "isDefault": false,
                    "createdAt": "2025-10-10T15:30:02.535Z",
                    "updatedAt": "2026-04-22T16:07:18.618Z"
                },
                {
                    "userCashBalanceId": "1c1b5fcc-eb21-44c5-b678-9c41f3fa21b4",
                    "totalCashBalance": "36.00",
                    "availableCashBalance": "36.00",
                    "lifetimeCashBalance": "177.00",
                    "nickname": "austin1",
                    "status": "ACTIVE",
                    "isDefault": false,
                    "createdAt": "2026-02-27T22:18:28.814Z",
                    "updatedAt": "2026-04-22T15:43:52.031Z"
                },
                {
                    "userCashBalanceId": "6d1b4b19-deef-42f5-80d7-ec34804ce090",
                    "totalCashBalance": "425108.80",
                    "availableCashBalance": "425108.80",
                    "lifetimeCashBalance": "444096.44",
                    "nickname": "Main account",
                    "status": "ACTIVE",
                    "isDefault": true,
                    "createdAt": "2025-08-01T19:25:54.392Z",
                    "updatedAt": "2026-04-21T19:19:22.777Z"
                }
            ],
            "totalCount": 3,
            "hasNextPage": false
        }
    }
}
```

### 篩選選項

| 欄位                | 型別                        | 說明             |
| :---------------- | :------------------------ | :------------- |
| userCashBalanceId | \[UUID!]                  | 依特定消費帳戶 ID 篩選  |
| nickname          | \[String!]                | 依消費帳戶暱稱篩選      |
| status            | \[UserCashBalanceStatus!] | 依消費帳戶狀態篩選      |
| isDefault         | Boolean                   | 依是否為預設消費帳戶進行篩選 |
| createdGte        | DateTime                  | 依建立時間（大於或等於）篩選 |
| createdLte        | DateTime                  | 依建立時間（小於或等於）篩選 |
| updatedGte        | DateTime                  | 依更新時間（大於或等於）篩選 |
| updatedLte        | DateTime                  | 依更新時間（小於或等於）篩選 |

**範例 - 僅取得 `ACTIVE` 的消費帳戶**

```json theme={null}
{
	"filter": {
  	"status": [ACTIVE]
  }
}
```

### 分頁

| 欄位     | 型別  | 預設值 | 最大值 | 說明         |
| ------ | --- | --- | --- | ---------- |
| limit  | Int | 20  | 20  | 每頁要回傳的交易數量 |
| offset | Int | 0   | -   | 要略過的交易數量   |

**範例 - 第 1 頁**：

```json theme={null}
{
	"paginate": {
  	"limit": 20,
  	"offset": 0
  }
}
```

**範例 - 第 2 頁**：

```json theme={null}
{
	"paginate": {
  	"limit": 20,
  	"offset": 20,
	}
}
```

## 取得特定消費帳戶

若要取得在您帳戶下建立的特定消費帳戶，請使用 `getUserCashBalanceById` 查詢。此呼叫會回傳該消費帳戶的詳細資訊，包括 `userCashBalanceId` 與其餘額。

### 變數

| 欄位                | 型別      | 必填 | 說明       |
| ----------------- | ------- | -- | -------- |
| userCashBalanceId | String! | 是  | 消費帳戶的 ID |

### 範例請求

```graphql theme={null}
query GetUserCashBalanceById(
  $userCashBalanceId: String
) {
  getUserCashBalanceById(
    userCashBalanceId: $userCashBalanceId
  ) {
    userCashBalanceId
    totalCashBalance
    availableCashBalance
    lifetimeCashBalance
    nickname
    status
    isDefault
    createdAt
    updatedAt
  }
}
```

### 範例回應

回應將包含特定消費帳戶的詳細資訊

```json JSON theme={null}
{
    "data": {
        "getUserCashBalanceById": {
            "userCashBalanceId": "6d1b4b19-deef-42f5-80d7-ec34804ce090",
            "totalCashBalance": "425108.80",
            "availableCashBalance": "425108.80",
            "lifetimeCashBalance": "444096.44",
            "nickname": "Main account",
            "status": "ACTIVE",
            "isDefault": true,
            "createdAt": "2025-08-01T19:25:54.392Z",
            "updatedAt": "2026-04-21T19:19:22.777Z"
        }
    }
}
```

<br />