Skip to Content
WonderMoney Docs
Alojamiento propio

Añadir un proveedor bancario

Implementa un nuevo agregador bancario detrás de la interfaz BankProvider, regístralo y mantén la sincronización independiente del proveedor.

WonderMoney sincroniza cuentas a través de una interfaz de proveedor, así que añadir un agregador no toca los servicios de sincronización. Enable Banking es la implementación de referencia y SimpleFIN una segunda, basada en token; esta página es la lista de comprobación para la siguiente.

El punto de extensión

Todo vive en apps/api/src/services/bank-providers/:

  • types.ts — la interfaz BankProvider, la referencia de conexión que lee la sincronización y las formas normalizadas de cuenta, saldo y transacción.
  • errors.ts — los fallos tipados que lanza un proveedor: RateLimitedError, ConsentExpiredError, UserActionRequiredError, UnavailableError. Se asignan a los códigos de incidente (rate_limited, consent_expired, authentication, provider_unavailable), así que los servicios de sincronización nunca conocen la forma de error de tu proveedor. ProviderReportedError lleva un problema que el agregador indicó para una cuenta (un BankReportedErrorCode, como unsupported_currency).
  • registry.ts — los proveedores compilados y el filtro de activación BANK_PROVIDERS.
  • enable-banking.provider.ts — la implementación de referencia, con redirección de consentimiento.
  • simplefin.provider.ts — un proveedor que se conecta con un token de configuración en lugar de una redirección. Rechaza los métodos del flujo de consentimiento, se conecta por su propia ruta (services/simplefin/) y lee todas las cuentas en una sola petición por sincronización.

Los servicios de sincronización (account-initial-sync-account.service.ts, account-initial-sync-transaction.service.ts) importan solo types.ts. Nunca importan el cliente o la entidad de un proveedor y nunca ramifican por el nombre del proveedor.

1. Implementa BankProvider

Crea my-provider.provider.ts e implementa:

MétodoLo que necesita la sincronización
listInstitutionsEl selector de bancos: un id estable, nombre, país y logotipo.
startConnectionInicia el flujo de consentimiento y devuelve la URL que abre el navegador. Persiste aquí tu fila de conexión.
completeConnectionCanjea el código del callback, marca la conexión como activa y persiste sus cuentas. Devuelve bankConnectionKey, accountsCreated y el destino del navegador.
getSessionStatusSi el consentimiento sigue vigente (active, ended, unknown), usado después de que se rechacen todas las cuentas.
listAccountsLas cuentas de la conexión con moneda, IBAN, titular e id de la institución. Define reportedErrorCode para un problema que el agregador indicó sin dejar de responder, como la lista de errores de SimpleFIN: la ejecución queda entonces registrada como parcial con ese código.
getBalancesLos saldos de la cuenta, con un balanceType que entiende la lista de preferencias (closingBooked, interimBooked, expected, …).
getTransactionsLa ventana completa, ya dividida en booked, pending y voided. Pagina internamente; la sincronización llama una vez por cuenta.

Declara también estas capacidades:

  • transactionIdentity — la columna de Transaction que guarda el id de tu proveedor y el prefijo del id estable para filas sin id. Un proveedor con ids estables y únicos dentro de cada cuenta puede usar la columna genérica nordigenInternalTransactionId con ids prefijados por el proveedor, como hace SimpleFIN (simplefin:<id>). Enable Banking mantiene su propia columna, por sus reglas de ids inestables.
  • institutionProvider — el valor de AccountFinancialInstitution.provider de tus cuentas. other existe para proveedores nuevos.
  • consentExpires — ponlo en false cuando el acceso no tiene fecha de fin, como con SimpleFIN: la conexión deja accessValidUntil vacío y el planificador la sigue sincronizando. Omitido significa que el consentimiento caduca.

Lanza los errores tipados de errors.ts en todas las llamadas. No dejes escapar la forma de error de tu SDK: las comprobaciones de límite de peticiones y de consentimiento leen los errores tipados (y el status que llevan).

2. Regístralo

Añade el proveedor a PROVIDERS en registry.ts y exporta su id. El operador lo activa con una variable de entorno separada por comas:

BANK_PROVIDERS=enable_banking,my_provider

Sin valor o vacía, se activan todos los proveedores compilados salvo los opcionales de OPT_IN_PROVIDERS, hoy SimpleFIN. Haz opcional un proveedor cuando contacta con un servicio de pago o regional en nombre del usuario. GET /v1/instance informa la lista en features.bankSyncProviders, y features.bankSync es falso cuando no hay ninguno activo. Los clientes ocultan la función a partir de esa lista, así que mantén los ids estables.

3. Persiste la conexión

La sincronización lee BankConnection (la fila independiente del proveedor: proveedor, id externo, estado, accessValidUntil, referencia de la credencial, marcas de sincronización). Mantén los campos específicos del proveedor (nombre del ASPSP, FK de la credencial, id de sesión) en tu propia fila de detalle y enlázala uno a uno mediante bankConnectionKey, como hace EnableBankingConnection.

Las migraciones de este repositorio son solo DDL. Si hay que mover filas existentes a una tabla o columna nueva, escribe un backfill de arranque idempotente y transaccional (ver bank-connection-backfill.service.ts y su llamada en migrate.ts), no una migración de datos. Debe poder ejecutarse en cada arranque y una segunda ejecución no debe cambiar nada.

4. Prueba el punto de extensión

  • Prueba unitariamente el mapeo y la traducción de errores del proveedor.
  • Ejecuta una sincronización completa a través de la interfaz con un proveedor falso: services/bank-providers/__tests__/fake-provider-sync.test.ts crea una conexión, llama a runBankSyncPhases y comprueba las filas de cuenta y transacción.
  • Si añades un backfill, pruébalo con datos con la forma real y confirma que una segunda ejecución no hace nada (bank-connection-backfill.service.test.ts).

Ejecuta las pruebas afectadas con un Postgres desechable:

cd apps/api
TEST_POSTGRES_URL=postgres://user:pass@localhost:5432/wmdb pnpm vitest run src/services/bank-providers

Lista de comprobación

  • BankProvider implementado, errores tipados lanzados.
  • Registrado en registry.ts; BANK_PROVIDERS documentado.
  • BankConnection + fila de detalle escritas por startConnection/completeConnection.
  • Las cuentas llevan bankConnectionKey.
  • Migración DDL + snapshot; cualquier movimiento de datos es un backfill de ejecución idempotente.
  • Pasan la prueba de sincronización completa con proveedor falso y la de backfill.

On this page