Saltar al contenido principal
Un flujo bancario continuo da a un producto de contabilidad o de teneduría de libros los saldos y las transacciones de las cuentas bancarias de cada cliente todos los días, sin que el cliente tenga que volver a iniciar sesión. Con Didit creas un enlace con acceso continuo, recibes webhooks cuando llegan datos nuevos, lees solo lo que ha cambiado con un cursor, controlas cuándo termina el consentimiento y detienes o eliminas el acceso cuando el cliente se da de baja. Esta guía te lleva desde cero hasta un flujo diario para un cliente. El mismo código sirve para todos los clientes: una conexión por cliente y banco.

Qué necesitas

  • Una clave de API con el permiso de datos bancarios para tu aplicación de sandbox. Consulta el inicio rápido.
  • Un destino de webhook que reciba los eventos bank.*. Consulta Webhooks bancarios.
  • Una tabla en tu base de datos para el ID de conexión de cada cliente, el cursor del flujo de cambios y la finalización del consentimiento.

Paso 1: crea un enlace con acceso continuo

  • access: ongoing mantiene el acceso abierto hasta que termine el consentimiento. consent_days es una solicitud: el banco decide la fecha real, que se muestra en la conexión.
  • history_from solicita el historial desde una fecha, por ejemplo, el inicio del año. Usa history_days (de 1 a 365) si lo prefieres, pero nunca los dos. El banco podría entregar menos: cada cuenta informa de history_coverage.
  • ownership.compare: none omite la comparación del titular, así que no se necesita una identidad de referencia. Usa business para comparar el titular con una empresa verificada en Didit.
  • end_user.reference es tu identificador del cliente. Se puede buscar y permite que Didit reconozca al mismo cliente cuando vuelva a conectar las mismas cuentas.
  • Envía al cliente a la página alojada y devuélvelo a tu producto con una URL de redirección.
Guarda el id del enlace junto al cliente.

Paso 2: espera a que se complete la conexión

Cuando el cliente termina, llega bank.link.completed con el connection_id. Confírmalo, ya que nunca se debe confiar en el navegador:
Guarda el connection_id y espera a bank.connection.created: a partir de ese momento ya se pueden leer las cuentas, los saldos y las transacciones recientes (sync.initial_status es succeeded o partial). bank.connection.history_complete llega cuando termina la carga del histórico. Para cada cuenta, history_coverage.oldest_booking_date indica hasta qué fecha llegó realmente el banco.

Paso 3: cargar la primera copia

Un cursor vacío devuelve todas las transacciones actuales como added con reset: true. Recórrelas por páginas y guarda el cursor solo al final:
  • La primera lectura es una instantánea auténtica: devuelve cada transacción que tenía la conexión cuando empezó la lectura, cada una exactamente una vez como added, en su estado actual, aunque se ejecute una sincronización mientras recorres las páginas.
  • Los cambios hechos mientras recorrías las páginas llegan en la siguiente lectura desde next_cursor: una transacción que ya recibiste vuelve como modified, y una nueva llega como added.
  • Guarda next_cursor solo después de una respuesta con has_more: false.
  • Si la paginación falla a mitad de camino, reinicia desde el cursor que guardaste.
  • Lee los saldos con GET /v3/bank/accounts/{account_id}/balances/.

Paso 4: mantente al día con cada webhook

Didit sincroniza automáticamente cada conexión activa con acceso continuo entre una y cuatro veces al día, según el banco (sync.frequency_per_day). Cuando una sincronización guarda cambios, llega bank.data.updated con el connection_id, los account_ids y los recuentos. Consulta el feed de cambios con tu cursor guardado:
  • added son transacciones nuevas, incluidas las pendientes.
  • modified son transacciones que cambiaron, en su estado actual. Aplica cada una como upsert por id: si ya la tienes, se actualiza, y si aún no la tienes, se añade.
  • removed incluyen un reason. Ignora un id que no tengas. Cuando una transacción pendiente se contabiliza, sale en removed con pending_booked y la transacción contabilizada llega en added.
Usa el id de la transacción como clave: se mantiene igual en las lecturas, las sincronizaciones y las renovaciones. Revisa identity_quality: con derived, una corrección del banco puede aparecer como un removed y un added. Las lecturas no generan cargos, pero los datos solo cambian cuando se ejecuta una sincronización, así que una lectura por webhook es suficiente. Para obtenerlos antes, usa Sync Now: Actualizar datos bancarios bajo demanda.

Paso 5: gestionar el reinicio

Un cursor más antiguo que la ventana de reproducción responde 410 cursor_expired con bootstrap: true. El registro de cambios se puede reproducir durante 90 días, así que esto es poco frecuente en un trabajo diario. Empieza de nuevo desde un cursor vacío y reemplaza tu copia con el resultado en lugar de añadir datos a ella. Cada lectura desde un cursor vacío incluye reset: true, de modo que el mismo flujo de código gestiona una conexión nueva y un cursor expirado.

Paso 6: controla el vencimiento del consentimiento

El consentimiento tiene una fecha de vencimiento: consent.expires_at. Didit envía bank.connection.consent_expiring 14, 7 y 1 día antes de esa fecha. Llama a renew_connection cuando quieras renovar: responde 409 renewal_not_needed hasta que queden 30 días. La página en la que el cliente completa una renovación todavía no está disponible. Si el cliente deja caducar el consentimiento, la conexión pasa a renewal_required: aun así, puedes leer los datos que se sincronizaron. Encontrarás los detalles en Renovar un consentimiento bancario.

Paso 7: detener el acceso y eliminar

  • El cliente abandona tu producto: invoca revoke_connection para dejar de leer de inmediato, o delete_connection para dejar de leer y eliminar los datos almacenados.
  • El cliente deja de compartir en el banco: llega bank.connection.revoked con ended_by. Detén tu flujo de datos para esa conexión.

Precios

El acceso continuo se factura por conexión activa y por mes. El precio incluye todas las cuentas de la conexión, los saldos, las transacciones, hasta 365 días de historial cuando el banco lo entrega, las sincronizaciones automáticas, las sincronizaciones en vivo dentro de los límites del banco, las renovaciones, los webhooks y todas las lecturas. Un enlace que nadie completa es gratuito, y también lo son las conexiones en estado renewal_required, paused y revoked. Consulta precios.

Lista de verificación

  • Una conexión por cliente y banco, almacenada con su cursor y la fecha de finalización del consentimiento.
  • Manejador de webhooks idempotente, con el ID del evento como clave.
  • reset: true reemplaza tu copia, nunca agrega datos al final.
  • removed gestionado, con su motivo.
  • Recordatorios de consentimiento conectados a tu propio aviso al cliente.
  • bank.connection.revoked detiene el flujo de datos.
  • El plan de sandbox en Sandbox pasa las comprobaciones.
Última modificación el 22 de noviembre de 2026