Skip to main content

​
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 secretKey del paso anterior de integrar Bridge Connect.

​
Autenticación

Todas las solicitudes a la API de Bridge requieren dos tipos de autenticación:
  1. API Key - Tu clave de API obtenida del dashboard (como header Authorization: Bearer <api_key>)
  2. Secret Key - La clave secreta única de cada conexión recibida en el evento onSuccess (como header X-Secret-Key)
La combinación de ambas claves asegura que solo tu aplicación puede acceder a las cuentas de tus usuarios.

​
Listar Cuentas

Para obtener todas las cuentas asociadas a una conexión, utiliza el endpoint de lista de cuentas: 
curl https://api.bridge.com.do/connections/{connectionId}/accounts \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Secret-Key: <secret_key>"

​
Respuesta

{
  "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.

​
Obtener Detalles de una Cuenta

Si necesitas información de una cuenta específica: 
curl https://api.bridge.com.do/accounts/{accountId} \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Secret-Key: <secret_key>"
Ver detalles completos de la respuesta en la referencia del endpoint.

​
Listar Transacciones

Para obtener el historial de transacciones de una cuenta: 
curl https://api.bridge.com.do/accounts/{accountId}/transactions \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Secret-Key: <secret_key>"

​
Respuesta

{
  "transactions": [
    {
      "id": "txn_ckB4a8Ly6PojhwoT",
      "accountId": "acc_zP2oiEAvu7LnuUVc",
      "amount": -5000.0,
      "date": "2024-01-15T14:30:00Z",
      "description": "Compra en Supermercado Nacional",
      "reference": "REF123456",
      "status": "posted",
      "transactionRefresh": "txr_01J8XGKZP8K9V7J552EPPD89HM"
    },
    {
      "id": "txn_9xYzAb3cDeFgHiJk",
      "accountId": "acc_zP2oiEAvu7LnuUVc",
      "amount": 50000.0,
      "date": "2024-01-14T09:00:00Z",
      "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: 
# 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-Secret-Key: <secret_key>"

# 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-Secret-Key: <secret_key>"
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: 
curl "https://api.bridge.com.do/accounts/{accountId}/transactions?refreshedSince=txr_01J8XGKZP8K9V7J552EPPD89HM" \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Secret-Key: <secret_key>"
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.

​
Obtener Detalles de una Transacción

Para consultar una transacción específica: 
curl https://api.bridge.com.do/accounts/{accountId}/transactions/{transactionId} \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Secret-Key: <secret_key>"
Ver detalles completos de la respuesta en la referencia del endpoint.

​
Ejemplo Completo en JavaScript

const API_KEY = "tu_api_key";
const SECRET_KEY = "secret_key_de_la_conexion";
const CONNECTION_ID = "con_JNhdJbLyi55gZAUW";
const BASE_URL = "https://api.bridge.com.do";

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

  if (secretKey) {
    headers["X-Secret-Key"] = secretKey;
  }

  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, secretKey) {
  const data = await bridgeRequest(
    `/connections/${connectionId}/accounts`,
    secretKey
  );
  return data.accounts;
}

// 2. Obtener transacciones de una cuenta
async function getTransactions(accountId, secretKey, 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, secretKey);
  return data.transactions;
}

// Uso del ejemplo
(async () => {
  try {
    // Obtener cuentas
    const accounts = await getAccounts(CONNECTION_ID, SECRET_KEY);
    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, SECRET_KEY, {
        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);
  }
})();

​
Seguridad

Nunca expongas tus llaves de acceso en código del lado del cliente. Todas las llamadas a la API de Bridge deben hacerse desde tu servidor backend.
La combinación de tu API Key (clave de acceso) y el Secret Key de la conexión es lo que autoriza el acceso a los datos financieros de una conexión específica. Ambas claves son necesarias para acceder a la información. Mejores prácticas:
  • Guarda las claves de forma segura
  • No las registres en logs
  • No las incluyas en URLs
  • Transmítelas solo a través de conexiones HTTPS

​
Manejo de Errores

Los códigos de error comunes incluyen:
  • 401 Unauthorized - API Key inválida o faltante
  • 403 Forbidden - Secret Key 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