Skip to Content
WonderMoney Docs
Alojamento próprio

Adicionar um fornecedor bancário

Implementa um novo agregador bancário atrás da interface BankProvider, regista-o e mantém a sincronização independente do fornecedor.

O WonderMoney sincroniza contas através de uma interface de fornecedor, por isso adicionar um agregador não altera os serviços de sincronização. O Enable Banking é a implementação de referência e o SimpleFIN uma segunda, baseada em token; esta página é a lista de verificação para a próxima.

O ponto de extensão

Tudo vive em apps/api/src/services/bank-providers/:

  • types.ts — a interface BankProvider, a referência de ligação que a sincronização lê e as formas normalizadas de conta, saldo e transação.
  • errors.ts — as falhas tipadas que um fornecedor lança: RateLimitedError, ConsentExpiredError, UserActionRequiredError, UnavailableError. Mapeiam para os códigos de incidente (rate_limited, consent_expired, authentication, provider_unavailable), por isso os serviços de sincronização nunca conhecem a forma de erro do teu fornecedor. ProviderReportedError leva um problema que o agregador indicou para uma conta (um BankReportedErrorCode, como unsupported_currency).
  • registry.ts — os fornecedores compilados e o filtro de ativação BANK_PROVIDERS.
  • enable-banking.provider.ts — a implementação de referência, com redirecionamento de consentimento.
  • simplefin.provider.ts — um fornecedor ligado com um token de configuração em vez de um redirecionamento. Recusa os métodos do fluxo de consentimento, liga-se pela sua própria rota (services/simplefin/) e lê todas as contas num só pedido por sincronização.

Os serviços de sincronização (account-initial-sync-account.service.ts, account-initial-sync-transaction.service.ts) importam apenas types.ts. Nunca importam o cliente ou a entidade de um fornecedor e nunca ramificam pelo nome do fornecedor.

1. Implementa BankProvider

Cria my-provider.provider.ts e implementa:

MétodoO que a sincronização precisa
listInstitutionsO seletor de bancos: um id estável, nome, país e logótipo.
startConnectionInicia o fluxo de consentimento e devolve o URL que o navegador abre. Persiste a tua linha de ligação aqui.
completeConnectionTroca o código do callback, marca a ligação como ativa e persiste as contas. Devolve bankConnectionKey, accountsCreated e o destino do navegador.
getSessionStatusSe o consentimento ainda é válido (active, ended, unknown), usado depois de todas as contas serem rejeitadas.
listAccountsAs contas da ligação com moeda, IBAN, titular e id da instituição. Define reportedErrorCode para um problema que o agregador indicou sem deixar de responder, como a lista de erros do SimpleFIN: a execução fica então registada como parcial com esse código.
getBalancesOs saldos da conta, com um balanceType que a lista de preferências entende (closingBooked, interimBooked, expected, …).
getTransactionsA janela completa, já dividida em booked, pending e voided. Pagina internamente; a sincronização chama isto uma vez por conta.

Declara também estas capacidades:

  • transactionIdentity — a coluna de Transaction que guarda o id do teu fornecedor e o prefixo do id estável para linhas sem id. Um fornecedor com ids estáveis e únicos dentro de cada conta pode usar a coluna genérica nordigenInternalTransactionId com ids prefixados pelo fornecedor, como faz o SimpleFIN (simplefin:<id>). O Enable Banking mantém a sua própria coluna, pelas suas regras de ids instáveis.
  • institutionProvider — o valor de AccountFinancialInstitution.provider das tuas contas. other existe para novos fornecedores.
  • consentExpires — define-o como false quando o acesso não tem data de fim, como no SimpleFIN: a ligação deixa accessValidUntil vazio e o agendador continua a sincronizá-la. Omitido significa que o consentimento expira.

Lança os erros tipados de errors.ts em todas as chamadas. Não deixes escapar a forma de erro do teu SDK: as verificações de limite de pedidos e de consentimento leem os erros tipados (e o status que transportam).

2. Regista-o

Adiciona o fornecedor a PROVIDERS em registry.ts e exporta o seu id. O operador ativa-o com uma variável de ambiente separada por vírgulas:

BANK_PROVIDERS=enable_banking,my_provider

Sem valor ou vazia, ficam ativos todos os fornecedores compilados exceto os opcionais de OPT_IN_PROVIDERS, hoje o SimpleFIN. Torna um fornecedor opcional quando ele contacta um serviço pago ou regional em nome do utilizador. GET /v1/instance reporta a lista em features.bankSyncProviders, e features.bankSync é falso quando nenhum está ativo. Os clientes escondem a funcionalidade a partir dessa lista, por isso mantém os ids estáveis.

3. Persiste a ligação

A sincronização lê BankConnection (a linha independente do fornecedor: fornecedor, id externo, estado, accessValidUntil, referência da credencial, marcas de sincronização). Mantém os campos específicos do fornecedor (nome do ASPSP, FK da credencial, id da sessão) na tua própria linha de detalhe e liga-a um-para-um através de bankConnectionKey, como faz a EnableBankingConnection.

As migrações neste repositório são apenas DDL. Se linhas existentes tiverem de passar para uma nova tabela ou coluna, escreve um backfill de arranque idempotente e transacional (ver bank-connection-backfill.service.ts e a chamada em migrate.ts), não uma migração de dados. Tem de ser seguro correr em cada arranque e uma segunda execução não pode alterar nada.

4. Testa o ponto de extensão

  • Testa unitariamente o mapeamento e a tradução de erros do fornecedor.
  • Corre uma sincronização completa através da interface com um fornecedor falso: services/bank-providers/__tests__/fake-provider-sync.test.ts cria uma ligação, chama runBankSyncPhases e verifica as linhas de conta e transação.
  • Se adicionares um backfill, testa-o com dados com a forma real e confirma que uma segunda execução não faz nada (bank-connection-backfill.service.test.ts).

Corre os testes afetados com um Postgres descartável:

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

Lista de verificação

  • BankProvider implementado, erros tipados lançados.
  • Registado em registry.ts; BANK_PROVIDERS documentado.
  • BankConnection + linha de detalhe escritas por startConnection/completeConnection.
  • As contas têm bankConnectionKey.
  • Migração DDL + snapshot; qualquer movimento de dados é um backfill de execução idempotente.
  • Teste de sincronização completa com fornecedor falso e teste de backfill passam.

On this page