Conexión bancaria para tu app, sin agregador

Si construyes una aplicación de finanzas personales ya conoces el muro: leer los movimientos bancarios de tus usuarios de forma programática pasa por pagar a un agregador, y el precio de entrada está fuera del alcance de un equipo pequeño. Habeas es otra vía. Es gratis, es software libre y puede usarlo cualquier aplicación.

La versión corta. Habeas es una extensión de navegador que instala tu usuario. Lee sus propios datos desde su propia sesión autenticada, en su equipo, y los entrega a un endpoint de tu dominio. Sin scraping en servidor, sin guardar credenciales, sin un tercero acumulando el historial financiero de nadie.

Cómo funciona

Tu usuario instala Habeas y activa las fuentes que le interesan (su banco, su bróker).
Tu aplicación pide la conexión. Habeas abre su propia pantalla de consentimiento. No corre nada hasta que el usuario aprueba ahí.
Los datos llegan a tu endpoint, ya normalizados, según van apareciendo. Tú confirmas lo que has guardado de verdad; el resto se reintenta.

Dos formas de integrarlo

Pull — los pides tú

Propones una fuente concreta y, una vez el usuario la aprueba, puedes lanzar la recolección cuando quieras (un botón «Sincronizar» en tu interfaz).

await habeas('propose-workflow', {
  source: 'ing-es',
  sink: {
    type: 'http',
    url: 'https://tu-app.com/ingest',
    headers: { 'x-pair-token': '…' },
  },
});
// y más adelante:
await habeas('collect', { grantId });

Push — te los envían

Te registras solo como destino, sin fuente y sin permiso para pedir nada. El usuario dirige hacia ti las fuentes que quiera, desde Habeas.

await habeas('register-sink', {
  sink: {
    type: 'http',
    url: 'https://tu-app.com/ingest',
    headers: { 'x-pair-token': '…' },
  },
});

Las dos están documentadas en external-hooks.md. La mayoría empieza por pull y añade push después.

Qué recibes

Registros normalizados, no HTML en bruto: fecha, importe con signo, concepto, saldo, un identificador para deduplicar y la cuenta a la que pertenecen. Cada registro conserva además los campos originales de la fuente, así que no se pierde nada.
Banca y bróker. Movimientos bancarios y, en bróker, operaciones y movimientos de efectivo (títulos, precio, comisiones, retención, instrumento).
Solo lo nuevo. Habeas lleva un registro de entregas por destino, así que resincronizar no te reenvía lo que ya tienes.
Confirmación por registro. Tu endpoint responde con los identificadores que ha incorporado realmente; lo demás queda pendiente y se reintenta. Sin pérdidas silenciosas.

Las reglas que hacen que esto sea seguro

Están implementadas en el código, no prometidas en un contrato:

Ligado al origen. El host del endpoint tiene que ser el de tu propio dominio. Un sitio solo puede dirigir los datos hacia sí mismo. No hay lista blanca porque no hace falta.
Consentimiento explícito. No se registra ni se ejecuta nada hasta que el usuario lo aprueba en la pantalla de Habeas, y un permiso existente nunca puede ampliarse en silencio.
Nunca credenciales. Habeas no lee, ni guarda, ni escribe las contraseñas de tu usuario. Entra él, incluido el segundo factor.
Revocable. El usuario puede retirar cualquier integración cuando quiera desde los ajustes de Habeas.

El banco que necesitan tus usuarios: pueden añadirlo ellos

La objeción evidente a cualquier catálogo es «el banco de mis usuarios no está». Aquí está lo importante: nadie tiene que esperar a que lo añadamos nosotros.

La lectura ocurre dentro de la sesión del propio titular, así que quien puede enseñarle un banco nuevo a Habeas es quien ya es cliente de ese banco, no nosotros. Por eso la extensión trae un grabador justo para eso, en Ajustes → Grabar y contribuir:

El usuario navega por su banco como haría normalmente, con su sesión iniciada, mientras graba.
Habeas redacta el borrador de la fuente solo a partir de lo que ha visto (endpoints, paginación, campos) y el usuario mapea lo que falte en un editor visual, con un botón Test que se ejecuta contra su sesión viva: ve filas reales antes de compartir nada.
Lo que nos llega va redactado: cada valor sustituido por un marcador de tipo, solo sobrevive la estructura. Escribimos y verificamos la fuente sin ver jamás sus datos.
Una vez publicada, esa fuente sirve para todos: tus usuarios y los nuestros.

Nadie escribe una línea de código, y una fuente es un fichero de definición y no un programa, que es lo que permite que esto sea un bien común. Si prefieres escribir una a mano, esa vía también está abierta: AUTHORING-SOURCES.md y ASSISTED-AUTHORING.md.

Esta es la parte donde colaborar sale a cuenta de verdad. Los adaptadores son fontanería compartida; donde compites es en el producto que construyes encima.

Lo que no es

Para que decidas con las contrapartidas reales sobre la mesa:

No es sincronización silenciosa en segundo plano. Tu usuario tiene que tener sesión activa; si no la hay, Habeas le saca la pestaña de acceso y espera. Es una decisión de diseño, no una carencia.
Las fuentes hay que mantenerlas. Cuando un servicio cambia su web, su definición se actualiza. La diferencia es que puedes arreglarlo tú mismo en vez de esperar a la hoja de ruta de un proveedor.
Funciona en navegadores de escritorio, que es donde vive la extensión.
Cada servicio tiene sus condiciones de uso, y cumplirlas es responsabilidad de quien lo usa. Habeas opera sobre los datos propios de una persona, en su propia sesión.

Por dónde empezar

Guía de integración Referencia de la API Código (AGPL-3.0)

Habeas está bajo AGPL-3.0: si lo mejoras, las mejoras vuelven al común. Cuéntamo fue la primera aplicación en integrarlo, y no pretende ser la última.

¿Estás construyendo algo y te topaste con el mismo muro? Abre un issue en GitHub o escribe a hola@habeas.dev.