O Poder da Idempotência em APIs Financeiras

Se há um pesadelo que assombra qualquer Tech Lead, é o conceito de transações duplicadas. Um utilizador clica duas vezes no botão de pagamento porque a internet estava lenta, e de repente foi cobrado duas vezes pelo mesmo pedido.

Como mitigamos isto sem impactar a experiência de uso? Com Idempotência.

O que é Idempotência?

Em termos simples, uma operação idempotente é aquela que produz o mesmo resultado, quer seja executada uma vez ou múltiplas vezes. Na engenharia financeira, isto significa que um pedido de pagamento submetido 10 vezes com a mesma chave (Idempotency Key) só será cobrado 1 vez.

Operações Atómicas no Banco de Dados

Não basta confiar no lado do cliente (Frontend) bloqueando o botão (ex: disabled=true). É muito fácil contornar essas validações manipulando a rede ou com scripts. A verdadeira defesa está na camada de dados.

O uso de transações de Base de Dados (DB Transactions) atómicas é fundamental. Ao envolver a criação de um pagamento e a verificação do estado num bloco atómico (DB::transaction ou equivalente), garantimos que processos concorrentes (duas requests no exato milissegundo) não leiam o estado "Não pago" simultaneamente e processem ambas o débito.

Guardas contra "Limbo"

Quando lidamos com chamadas externas (ex: APIs de bancos), o estado do sistema pode ficar em "limbo" se ocorrer uma quebra de ligação. Implementar guards de idempotência ajuda a que os reconciliadores consigam recuperar o estado real consultando o gateway usando a chave única enviada inicialmente, resgatando o pagamento sem nunca o duplicar.

Nunca confie no cliente. Torne as suas APIs burras no frontend, mas blindadas no backend.