O problema
Cada instituição que quer cobrar por referência Multicaixa tem de integrar, manter e reconciliar sozinha um gateway de pagamentos. É trabalho repetido, e os erros custam dinheiro: uma cobrança duplicada ou um pagamento por confirmar são problemas reais para uma família e para uma escola.
O objectivo foi centralizar essa integração numa API que serve muitas instituições ao mesmo tempo, com a garantia de que os dados de uma nunca se misturam com os de outra.
A abordagem
- 01
Isolamento entre clientes na camada de dados
O filtro por instituição é aplicado por baixo do código de negócio, no acesso à base. Se faltar o contexto do cliente, a consulta falha em vez de devolver dados de todos. Nenhuma rota depende de alguém se lembrar de escrever o filtro.
- 02
Idempotência de ponta a ponta
Cada pedido de escrita leva uma chave de idempotência, guardada com o hash do corpo. Do lado da liquidação, uma restrição única na base impede creditar o mesmo pagamento duas vezes, mesmo que o aviso chegue repetido ou em simultâneo.
- 03
Reler o pagamento no gateway antes de creditar
Um webhook pode ser forjado, repetido ou nunca chegar. Quando chega um, a API relê o estado da cobrança directamente no gateway e só então credita. Uma tarefa periódica de reconciliação apanha os pagamentos cujo aviso se perdeu.
- 04
Contrato gerado do código
O OpenAPI e o catálogo de erros são gerados a partir do código, e a integração contínua falha se o contrato publicado divergir do que a API faz.
- 05
Testes de carga
Escrevi testes de carga para a criação de cobranças, os webhooks de entrada, o calendário de cobrança e o envio de mensagens. Foram eles que mostraram que o worker de webhooks processava um aviso de cada vez.