Saltar para o conteúdo
Henrique Vieira
Todos os projectos

API de cobranças por referência Multicaixa, multi-tenant

AutoPropina

Uma API que deixa escolas e clínicas cobrar por referência Multicaixa sem que cada uma tenha de integrar o gateway de pagamentos.

Papel
Autor único: arquitectura, backend, consola, sítio e operação
Período
Set 2026 - presente
Estado
Em piloto
Tecnologias
TypeScriptNestJSPrismaPostgreSQLRedisBullMQNext.jsPlaywrightDocker

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

Os resultados

69 ms
p95 da criação de cobranças, a cerca de 170 cobranças/s por instância
605 s -> 119 s
confirmação de 3 000 pagamentos simultâneos, depois de paralelizar o worker
0
cobranças perdidas ou repetidas, com cada notificação entregue em duplicado
100%
dos achados da revisão ofensiva de segurança corrigidos, cada um com teste de regressão
83
operações no contrato OpenAPI, verificadas em cada alteração

O que aprendi

O maior ganho veio de um sítio que só os testes mostraram: o worker de webhooks. Passei a medir antes de optimizar, e a guardar junto de cada número a máquina e a carga com que foi obtido.

Caso seguinte

Facturação electrónica

Software para a AGT, multi-tenant

Ler o caso