> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bridge.com.do/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar Balances y Transacciones

> Cómo obtener información de cuentas bancarias conectadas

## Introducción

Una vez que tus usuarios han conectado sus cuentas bancarias usando Bridge Connect, puedes acceder a sus balances actuales y el historial completo de transacciones.

Esta guía asume que ya tienes el `connectionId` y `scopedToken` del paso anterior de [integrar Bridge Connect](/guides/connect).

## Autenticación

Todas las solicitudes en esta guía requieren ambas credenciales de acceso. Para una explicación detallada de cada una, consulta la [guía de autenticación](/guides/authentication).

| Header           | Valor                        |
| ---------------- | ---------------------------- |
| `Authorization`  | `Bearer <tu_clave_de_api>`   |
| `X-Scoped-Token` | `<token_de_acceso_limitado>` |

## Listar Cuentas

Para obtener todas las cuentas asociadas a una conexión, utiliza el endpoint de lista de cuentas:

```bash theme={null}
curl https://api.bridge.com.do/connections/{connectionId}/accounts \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Scoped-Token: <scoped_token>"
```

### Respuesta

```json theme={null}
{
  "accounts": [
    {
      "id": "acc_zP2oiEAvu7LnuUVc",
      "connectionId": "con_JNhdJbLyi55gZAUW",
      "type": "depository",
      "name": "Cuenta de Ahorros",
      "lastFour": "1234",
      "balance": {
        "current": 150000.5,
        "available": 150000.5
      },
      "currency": "DOP",
      "lastTransactionRefresh": "txr_01J8XGKZP8K9V7J552EPPD89HM"
    },
    {
      "id": "acc_8kLmN3qR9vTxYzAb",
      "connectionId": "con_JNhdJbLyi55gZAUW",
      "type": "credit",
      "name": "Tarjeta de Crédito Visa",
      "lastFour": "5678",
      "balance": {
        "current": -25000.0,
        "available": 75000.0,
        "limit": 100000.0
      },
      "currency": "DOP",
      "lastTransactionRefresh": "txr_01J8XGKZP8K9V7J552EPPD89HM"
    }
  ]
}
```

Ver detalles completos de la respuesta en la [referencia del endpoint](/api-reference/endpoint/list-accounts).

## Obtener Detalles de una Cuenta

Si necesitas información de una cuenta específica:

```bash theme={null}
curl https://api.bridge.com.do/accounts/{accountId} \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Scoped-Token: <scoped_token>"
```

Ver detalles completos de la respuesta en la [referencia del endpoint](/api-reference/endpoint/get-account).

## Listar Transacciones

Para obtener el historial de transacciones de una cuenta:

```bash theme={null}
curl https://api.bridge.com.do/accounts/{accountId}/transactions \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Scoped-Token: <scoped_token>"
```

### Respuesta

```json theme={null}
{
  "transactions": [
    {
      "id": "txn_ckB4a8Ly6PojhwoT",
      "accountId": "acc_zP2oiEAvu7LnuUVc",
      "amount": -5000.0,
      "date": "2024-01-15",
      "description": "Compra en Supermercado Nacional",
      "reference": "REF123456",
      "status": "posted",
      "transactionRefresh": "txr_01J8XGKZP8K9V7J552EPPD89HM"
    },
    {
      "id": "txn_9xYzAb3cDeFgHiJk",
      "accountId": "acc_zP2oiEAvu7LnuUVc",
      "amount": 50000.0,
      "date": "2024-01-14",
      "description": "Depósito Nómina",
      "reference": "DEP987654",
      "status": "posted",
      "transactionRefresh": "txr_01J8XGKZP8K9V7J552EPPD89HM"
    }
  ]
}
```

### Filtrar por Fecha

Puedes filtrar transacciones por rango de fechas usando los siguientes parámetros:

```bash theme={null}
# Transacciones desde el 1 de enero de 2024
curl "https://api.bridge.com.do/accounts/{accountId}/transactions?date[gte]=2024-01-01" \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Scoped-Token: <scoped_token>"

# Transacciones entre dos fechas
curl "https://api.bridge.com.do/accounts/{accountId}/transactions?date[gte]=2024-01-01&date[lte]=2024-01-31" \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Scoped-Token: <scoped_token>"
```

Operadores de fecha disponibles:

* `date[gte]` - Mayor o igual que (desde)
* `date[lte]` - Menor o igual que (hasta)
* `date[gt]` - Mayor que (después de)
* `date[lt]` - Menor que (antes de)

### Filtrar por Actualización

Para obtener solo las transacciones que han sido creadas o actualizadas desde tu última consulta, utiliza el cursor `refreshedSince`:

```bash theme={null}
curl "https://api.bridge.com.do/accounts/{accountId}/transactions?refreshedSince=txr_01J8XGKZP8K9V7J552EPPD89HM" \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Scoped-Token: <scoped_token>"
```

Este cursor se obtiene del campo `lastTransactionRefresh` en la respuesta de cuentas, o del campo `transactionRefresh` de cualquier transacción.

Ver más detalles sobre filtros y la respuesta en la [referencia del endpoint](/api-reference/endpoint/list-transactions).

## Obtener Detalles de una Transacción

Para consultar una transacción específica:

```bash theme={null}
curl https://api.bridge.com.do/accounts/{accountId}/transactions/{transactionId} \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Scoped-Token: <scoped_token>"
```

Ver detalles completos de la respuesta en la [referencia del endpoint](/api-reference/endpoint/get-transaction).

## Ejemplo Completo en JavaScript

```javascript theme={null}
const API_KEY = "tu_api_key";
const SCOPED_TOKEN = "brdg_st_xxxxx"; // Token del usuario
const CONNECTION_ID = "con_JNhdJbLyi55gZAUW";
const BASE_URL = "https://api.bridge.com.do";

// Función auxiliar para hacer requests
async function bridgeRequest(endpoint, scopedToken = null) {
  const headers = {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  };

  if (scopedToken) {
    headers["X-Scoped-Token"] = scopedToken;
  }

  const response = await fetch(`${BASE_URL}${endpoint}`, { headers });

  if (!response.ok) {
    throw new Error(`Error ${response.status}: ${await response.text()}`);
  }

  return response.json();
}

// 1. Listar todas las cuentas de una conexión
async function getAccounts(connectionId, scopedToken) {
  const data = await bridgeRequest(
    `/connections/${connectionId}/accounts`,
    scopedToken,
  );
  return data.accounts;
}

// 2. Obtener transacciones de una cuenta
async function getTransactions(accountId, scopedToken, filters = {}) {
  let endpoint = `/accounts/${accountId}/transactions`;

  // Agregar filtros opcionales
  const params = new URLSearchParams();
  if (filters.dateFrom) params.append("date[gte]", filters.dateFrom);
  if (filters.dateTo) params.append("date[lte]", filters.dateTo);
  if (filters.refreshedSince)
    params.append("refreshedSince", filters.refreshedSince);

  if (params.toString()) {
    endpoint += `?${params.toString()}`;
  }

  const data = await bridgeRequest(endpoint, scopedToken);
  return data.transactions;
}

// Uso del ejemplo
(async () => {
  try {
    // Obtener cuentas
    const accounts = await getAccounts(CONNECTION_ID, SCOPED_TOKEN);
    console.log(`Encontradas ${accounts.length} cuentas:`);

    accounts.forEach((account) => {
      console.log(`\n${account.name} (${account.lastFour})`);
      console.log(`  Balance: ${account.balance.current} ${account.currency}`);
      if (account.balance.available) {
        console.log(
          `  Disponible: ${account.balance.available} ${account.currency}`,
        );
      }
    });

    // Obtener transacciones de la primera cuenta
    if (accounts.length > 0) {
      const accountId = accounts[0].id;

      // Últimos 30 días
      const dateFrom = new Date();
      dateFrom.setDate(dateFrom.getDate() - 30);

      const transactions = await getTransactions(accountId, SCOPED_TOKEN, {
        dateFrom: dateFrom.toISOString().split("T")[0],
      });

      console.log(`\n\nÚltimas transacciones de ${accounts[0].name}:`);
      transactions.slice(0, 10).forEach((tx) => {
        const type = tx.amount > 0 ? "Ingreso" : "Egreso";
        console.log(
          `${tx.date.split("T")[0]} | ${type} | ${Math.abs(tx.amount)} | ${tx.description}`,
        );
      });
    }
  } catch (error) {
    console.error("Error:", error.message);
  }
})();
```

## Manejo de Errores

Los códigos de error comunes incluyen:

* **`401 Unauthorized`** - API Key inválida o faltante
* **`403 Forbidden`** - Scoped Token inválido o sin permisos para acceder a este recurso
* **`404 Not Found`** - Conexión, cuenta o transacción no encontrada

Siempre implementa manejo de errores apropiado en tu aplicación para brindar una buena experiencia a tus usuarios.

## Próximos Pasos

* Explora la [referencia completa de la API](/api-reference)
* Revisa cómo [revocar conexiones](/api-reference/endpoint/revoke-connection) cuando los usuarios lo soliciten