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 interfaceBankProvider, 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.ProviderReportedErrorleva um problema que o agregador indicou para uma conta (umBankReportedErrorCode, comounsupported_currency).registry.ts— os fornecedores compilados e o filtro de ativaçãoBANK_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étodo | O que a sincronização precisa |
|---|---|
listInstitutions | O seletor de bancos: um id estável, nome, país e logótipo. |
startConnection | Inicia o fluxo de consentimento e devolve o URL que o navegador abre. Persiste a tua linha de ligação aqui. |
completeConnection | Troca o código do callback, marca a ligação como ativa e persiste as contas. Devolve bankConnectionKey, accountsCreated e o destino do navegador. |
getSessionStatus | Se o consentimento ainda é válido (active, ended, unknown), usado depois de todas as contas serem rejeitadas. |
listAccounts | As 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. |
getBalances | Os saldos da conta, com um balanceType que a lista de preferências entende (closingBooked, interimBooked, expected, …). |
getTransactions | A 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 deTransactionque 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éricanordigenInternalTransactionIdcom 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 deAccountFinancialInstitution.providerdas tuas contas.otherexiste para novos fornecedores.consentExpires— define-o comofalsequando o acesso não tem data de fim, como no SimpleFIN: a ligação deixaaccessValidUntilvazio 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_providerSem 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.tscria uma ligação, chamarunBankSyncPhasese 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-providersLista de verificação
-
BankProviderimplementado, erros tipados lançados. - Registado em
registry.ts;BANK_PROVIDERSdocumentado. -
BankConnection+ linha de detalhe escritas porstartConnection/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.
SimpleFIN para bancos dos EUA e do Canadá
Deixa as pessoas da tua instância sincronizar contas de bancos dos EUA e do Canadá através do SimpleFIN Bridge, e vê o que o servidor guarda e contacta quando o fazem.
Guia da API
Autentica-te na API REST do WonderMoney, escolhe o acesso do token e trata as respostas.