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

# Administrar poder de gasto

Una vez que se vincula una cuenta bancaria (ver *Vincular una cuenta bancaria de Plaid*), puedes leer su saldo y poder de gasto y, cuando necesites una lectura más reciente, activar una actualización de saldo en tiempo real.

## Qué significa el poder de gasto

**Poder de gasto** es cuánto puede gastar actualmente un usuario desde una cuenta bancaria vinculada. Se basa en el saldo más reciente conocido de la cuenta, reducido por los flujos de salida ACH recientes que aún no se han liquidado por completo. Cuando un usuario gasta desde la cuenta, esos montos se retienen durante aproximadamente tres días hábiles antes de que se compensen y dejen de contar contra el poder de gasto. (La ventana exacta de compensación se establece por banco y puede ser más corta).

Fluz mantiene actualizado automáticamente el saldo almacenado de cada cuenta vinculada. Cuando necesites una lectura más actual —por ejemplo, justo después de que un usuario mueva dinero dentro o fuera de su banco— solicita una **actualización en tiempo real** (limitada por tasa; ver abajo). Actualizar el saldo actualiza la cifra de poder de gasto derivada del saldo.

## Auth

Llama a `/api/v1/graphql` con un token Bearer de usuario de Fluz que incluya `MANAGE_PAYMENT`. La autenticación básica no está permitida en estos campos.

```http theme={null}
Authorization: Bearer <fluz-user-access-token>
```

## Obtener poder de gasto para una cuenta bancaria

```graphql theme={null}
query GetPlaidBankAccountSpendPower($input: PlaidBankAccountInput!) {
  getPlaidBankAccountSpendPower(input: $input) {
    bankAccountId
    spendPower
    availableSpendPower
    lastRecordedBalance
    pendingTransactions
    updatedAt
  }
}
```

```json theme={null}
{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}
```

**Campos de respuesta**

| Campo                 | Descripción                                                                                                                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lastRecordedBalance` | El saldo bancario más reciente conocido para la cuenta.                                                                                                                                                      |
| `pendingTransactions` | Flujos de salida ACH recientes (débitos de aproximadamente los últimos tres días hábiles) que aún no se han liquidado y todavía se retienen contra el saldo.                                                 |
| `availableSpendPower` | Lo que el usuario puede gastar ahora mismo, derivado del último saldo menos los pendientes. Se mueve inmediatamente después de una actualización de saldo en tiempo real.                                    |
| `spendPower`          | La cifra de poder de gasto con decisión de la cuenta. Puede actualizarse con una cadencia más lenta que el saldo, por lo que puede diferir brevemente de `availableSpendPower` después de una actualización. |
| `updatedAt`           | Cuándo se calculó la cifra por última vez.                                                                                                                                                                   |

## Obtener el último saldo almacenado

Para una cuenta bancaria:

```graphql theme={null}
query GetPlaidBankAccountBalance($input: PlaidBankAccountInput!) {
  getPlaidBankAccountBalance(input: $input) {
    platformItemId
    bankInstitutionAuthId
    bankAccountId
    amount
    current
    source
    trigger
    startedAt
  }
}
```

```json theme={null}
{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}
```

Para todas las cuentas conectadas del usuario:

```graphql theme={null}
query GetPlaidBankBalances($input: PlaidBankBalanceFilterInput) {
  getPlaidBankBalances(input: $input) {
    platformItemId
    bankInstitutionAuthId
    bankAccountId
    amount
    current
    source
    trigger
    startedAt
  }
}
```

## Actualizar una cuenta en tiempo real

Solicita una actualización de saldo en tiempo real, limitada por tasa, para una sola cuenta bancaria. Esto obtiene un saldo nuevo desde Plaid y actualiza el poder de gasto derivado del saldo.

```graphql theme={null}
mutation RefreshPlaidBankAccountBalance($input: PlaidBankAccountInput!) {
  refreshPlaidBankAccountBalance(input: $input) {
    status
    balances {
      bankAccountId
      amount
      current
      source
      trigger
      startedAt
    }
  }
}
```

```json theme={null}
{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}
```

### Límite de tasa para actualizaciones

Para controlar el costo, las actualizaciones en tiempo real están limitadas por tasa **por institución de Plaid**: una actualización en tiempo real por hora y seis actualizaciones en tiempo real por día. Una actualización solicitada dentro de una ventana de límite no vuelve a llamar a Plaid: devuelve el último saldo almacenado, por lo que la llamada aún tiene éxito y devuelve datos. Diseña tu UI para que un saldo devuelto no siempre se asuma como una lectura nueva en tiempo real.

## Actualizar todas las conexiones (en caché)

Solicita una actualización en caché de todos los datos bancarios de Plaid conectados para la cuenta autenticada.

```graphql theme={null}
mutation RefreshPlaidBankConnections {
  refreshPlaidBankConnections {
    status
    balances {
      bankAccountId
      amount
      current
    }
    verifyMembers {
      platformItemId
      bankInstitutionAuthId
    }
  }
}
```

Usa `refreshPlaidBankConnections` cuando quieras que el servicio de identidad realice su actualización en caché de todas las conexiones.

> Si se devuelve `verifyMembers`, una o más conexiones necesitan reparación. Usa el `platformItemId` para iniciar el flujo de re-vinculación — ver **Volver a vincular cuentas bancarias desconectadas**. Ten en cuenta que la mutación de cuenta única `refreshPlaidBankAccountBalance` **no** devuelve esta señal, así que usa `refreshPlaidBankConnections` cuando necesites detectar conexiones desconectadas.

<br />