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 interfazBankProvider, 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.ProviderReportedErrorlleva un problema que el agregador indicó para una cuenta (unBankReportedErrorCode, comounsupported_currency).registry.ts— los proveedores compilados y el filtro de activaciónBANK_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étodo | Lo que necesita la sincronización |
|---|---|
listInstitutions | El selector de bancos: un id estable, nombre, país y logotipo. |
startConnection | Inicia el flujo de consentimiento y devuelve la URL que abre el navegador. Persiste aquí tu fila de conexión. |
completeConnection | Canjea el código del callback, marca la conexión como activa y persiste sus cuentas. Devuelve bankConnectionKey, accountsCreated y el destino del navegador. |
getSessionStatus | Si el consentimiento sigue vigente (active, ended, unknown), usado después de que se rechacen todas las cuentas. |
listAccounts | Las 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. |
getBalances | Los saldos de la cuenta, con un balanceType que entiende la lista de preferencias (closingBooked, interimBooked, expected, …). |
getTransactions | La 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 deTransactionque 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éricanordigenInternalTransactionIdcon 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 deAccountFinancialInstitution.providerde tus cuentas.otherexiste para proveedores nuevos.consentExpires— ponlo enfalsecuando el acceso no tiene fecha de fin, como con SimpleFIN: la conexión dejaaccessValidUntilvací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_providerSin 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.tscrea una conexión, llama arunBankSyncPhasesy 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-providersLista de comprobación
-
BankProviderimplementado, errores tipados lanzados. - Registrado en
registry.ts;BANK_PROVIDERSdocumentado. -
BankConnection+ fila de detalle escritas porstartConnection/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.
SimpleFIN para bancos de EE. UU. y Canadá
Permite que las personas de tu instancia sincronicen cuentas de bancos de EE. UU. y Canadá a través de SimpleFIN Bridge, y qué guarda y contacta el servidor cuando lo hacen.
Guía de la API
Autentícate en la API REST de WonderMoney, elige el acceso del token y gestiona las respuestas.