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

# Obtener cuentas de gasto

Después de crear una cuenta de gasto, puedes acceder a ella mediante las siguientes consultas:

1. `getUserCashBalances` - recupera una lista de todas tus cuentas de gasto.
2. `getUserCashBalanceById` - recupera una cuenta de gasto específica según su valor de id.

<Warning>
  **Autorización requerida**

  Esta mutación requiere el alcance `LIST_PAYMENT`. Asegúrate de que tu token de acceso tenga concedido este alcance antes de intentar transferir fondos internamente.
</Warning>

## Detalles de la cuenta de gasto

El objeto `UserCashBalanceDetails` contendrá información importante sobre la cuenta de gasto.

| Nombre del campo     | Tipo                   | Descripción                                                                |
| :------------------- | :--------------------- | :------------------------------------------------------------------------- |
| userCashBalanceId    | UUID!                  | Identificador único para la cuenta de saldo en efectivo                    |
| totalCashBalance     | String!                | Saldo total en efectivo en la cuenta (comienza en 0)                       |
| availableCashBalance | String!                | Saldo en efectivo disponible para uso inmediato (comienza en 0)            |
| lifetimeCashBalance  | String!                | Total acumulado de todos los fondos depositados alguna vez (comienza en 0) |
| nickname             | String                 | El nombre personalizado asignado a la cuenta                               |
| status               | UserCashBalanceStatus! | Estado actual de la cuenta (ACTIVE, CLOSED)                                |
| isDefault            | Boolean!               | Indica si la cuenta de gasto es la predeterminada                          |
| createdAt            | DateTime!              | Marca de tiempo cuando se creó la cuenta                                   |
| updatedAt            | DateTime!              | Marca de tiempo cuando se actualizó la cuenta                              |

## Recuperar la lista de cuentas de gasto

Para obtener una lista de las cuentas de gasto creadas en tu cuenta, usa la consulta `getUserCashBalances`. Esta llamada devuelve una lista de cuentas de gasto con detalles básicos, incluido el `userCashBalanceId`. Necesitarás este ID para recuperar una cuenta de gasto específica mediante `getuserCashBalanceById`.

### Variables

| Campo    | Tipo                       | Requerido | Descripción                                                   |
| -------- | -------------------------- | --------- | ------------------------------------------------------------- |
| filter   | UserCashBalanceFilterInput | No        | Criterios de filtrado para cuentas de gasto                   |
| paginate | OffsetInput                | No        | Parámetros de paginación (predeterminado: limit=20, offset=0) |

### Solicitud de ejemplo

```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>
  Ten en cuenta que, debido a la limitación de velocidad, es posible que necesites paginar y llamar a la lista de cuentas de gasto varias veces.
</Note>

### Respuesta de ejemplo

La respuesta contendrá una lista de cuentas de gasto

```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
        }
    }
}
```

### Opciones de filtrado

| Campo             | Tipo                      | Descripción                                            |
| :---------------- | :------------------------ | :----------------------------------------------------- |
| userCashBalanceId | \[UUID!]                  | Filtrar por IDs específicos de cuentas de gasto        |
| nickname          | \[String!]                | Filtrar por apodos de las cuentas de gasto             |
| status            | \[UserCashBalanceStatus!] | Filtrar por estado de la cuenta de gasto               |
| isDefault         | Boolean                   | Filtrar por si la cuenta de gasto es la predeterminada |
| createdGte        | DateTime                  | Filtrar por fecha de creación (mayor o igual que)      |
| createdLte        | DateTime                  | Filtrar por fecha de creación (menor o igual que)      |
| updatedGte        | DateTime                  | Filtrar por fecha de actualización (mayor o igual que) |
| updatedLte        | DateTime                  | Filtrar por fecha de actualización (menor o igual que) |

**Ejemplo - Obtener solo cuentas de gasto `ACTIVE`**

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

### Paginación

| Campo  | Tipo | Predeterminado | Máx. | Descripción                                   |
| ------ | ---- | -------------- | ---- | --------------------------------------------- |
| limit  | Int  | 20             | 20   | Número de transacciones a devolver por página |
| offset | Int  | 0              | -    | Número de transacciones a omitir              |

**Ejemplo - Página 1**:

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

**Ejemplo - Página 2**:

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

## Recuperar una cuenta de gasto específica

Para obtener una cuenta de gasto específica creada en tu cuenta, usa la consulta `getUserCashBalanceById`. Esta llamada devuelve los detalles de esta cuenta de gasto, incluido el `userCashBalanceId` y sus saldos.

### Variables

| Campo             | Tipo    | Requerido | Descripción              |
| ----------------- | ------- | --------- | ------------------------ |
| userCashBalanceId | String! | Sí        | ID de la cuenta de gasto |

### Solicitud de ejemplo

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

### Respuesta de ejemplo

La respuesta contendrá los detalles de una cuenta de gasto específica

```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 />