Autor: Alisson Neves

Sistemas financeiros precisam ser idempotentes por padrão

Em quaisquer sistemas, falhas são inevitáveis. Redes caem, serviços ficam indisponíveis, mensagens são reenviadas e operações precisam ser reprocessadas. Mas o que não pode ser tido como inevitável é o efeito colateral dessas falhas.

É nesse ponto que a idempotência deixa de ser um detalhe técnico e passa a ser um requisito estrutural.

Mas o que é “idempotência”?

Idempotência é a propriedade de uma operação que garante que sua execução repetida, uma ou várias vezes, produz o mesmo efeito final que uma única execução.

Em sistemas financeiros, isso significa que uma mesma requisição, mesmo que reenviada por falhas de rede, retentativas automáticas ou reprocessamentos manuais, não pode gerar efeitos colaterais adicionais, como cobranças duplicadas, saldos incorretos ou estados inconsistentes.

Na Delfinance, utilizamos idempotência na API de Pix, por exemplo, para garantir que nenhuma operação seja erroneamente realizada mais de uma vez.

Falhas são normais, reprocessamento também

Em arquiteturas distribuídas, especialmente aquelas baseadas em eventos, filas e chamadas assíncronas, o reprocessamento não é exceção, é parte do fluxo habitual.

Alguns cenários comuns: 

• Timeout após o processamento efetivo, levando o cliente a reenviar a requisição 
• Retry automático de mensagens em filas
• Replays manuais para correção de falhas operacionais
• Recuperação após indisponibilidade parcial de serviços terceiros
• Envio duplicado de requisição única

Nesses cenários, executar a mesma operação mais de uma vez é esperado e aconselhável. O erro não está no reprocessamento, mas em sistemas que não foram projetados para lidar com ele.

Por que sistemas financeiros exigem idempotência por padrão

Diferente de sistemas puramente informacionais, sistemas financeiros lidam com dinheiro real, responsabilidade legal, auditoria e confiança do usuário. Um erro financeiro raramente é apenas técnico, ele se converte rapidamente em impacto financeiro direto, custos operacionais para correção, risco regulatório e perda de credibilidade.

Por isso, em sistemas financeiros bem desenvolvidos a pergunta correta não é “se haverá reprocessamento”, mas “quando“.

Muitos sistemas partem de premissas frágeis, como: “essa fila não duplica mensagens”, ou “esse endpoint só será chamado uma vez”, ou ainda “esse cliente não vai reenviar a requisição”. Na prática, nenhuma dessas garantias se sustenta em ambientes reais.

Protocolos de mensageria amplamente usados (como Kafka, RabbitMQ, SQS) operam com entrega pelo menos uma vez. Do ponto de vista de consistência financeira, isso significa que duplicatas são uma certeza estatística, não uma possibilidade remota.

Idempotência como mecanismo de segurança, não de otimização

Um erro comum é tratar idempotência como otimização, boa prática opcional ou responsabilidade do usuário. Mas em sistemas financeiros, idempotência é um mecanismo necessário de segurança de estado.

Ela protege o sistema contra retries automáticos, processamentos concorrentes e erros humanos em replays manuais. Assim como em transações de banco de dados, idempotência existe para preservar o domínio.

Idempotência nas APIs da Delfinance

Chave de idempotência

Toda operação sensível a efeitos colaterais, a exemplo de pagamentos e transferências, aceita uma chave única no cabeçalho da requisição, IdempotencyKey. Essa chave define a identidade da tentativa: se a mesma requisição for reenviada com a mesma chave, a API reapresenta a resposta já gerada e não executa o efeito novamente.

Um exemplo prático é a requisição de transferência na API de Core Bancário. Uma vez que a requisição é recebida por nossa API, a idempotência operacional é garantida, evitando débitos duplicados, além de prover rastreabilidade ponta a ponta.

Persistência antes do efeito

A regra é simples: registre a intenção antes de acionar qualquer efeito externo (ex.: iniciar um Pix). Ao persistir a intenção logo no início, a API consegue: 

• detectar duplicatas mesmo após timeout, queda de serviço ou retry agressivo; 
• retomar o processamento com segurança; 
• provar o que aconteceu (ou não aconteceu) em auditoria. 

Na API Pix da Delfinance, a intenção de envio é registrada antes do processamento efetivo. Isso significa que até tentativas interrompidas no meio do caminho continuam idempotentes: o sistema reconhece o pedido, sabe o estado, e evita repetir efeitos. 

Conclusão

Reprocessar não deveria ser perigoso. Se uma operação financeira não pode ser executada duas vezes sem causar dano, o problema não está no retry, mas no design. Sistemas financeiros maduros não tratam idempotência como exceção. Eles a adotam por padrão, como parte da própria definição de correção.

É essa visão que orienta o desenvolvimento das APIs da Delfinance, projetadas desde a origem para operar com segurança, previsibilidade e consistência, mesmo sob falhas, reprocessamentos e alta escala.

Deseja conhecer mais sobre nossas APIs de Pix, Cobrança, Bancarização e outros produtos?

Agora, se quiser saber como migramos o banco de dados da API de Pix com zero downtime e sem impacto negativo para nossos clientes, leia: O dia em que precisamos trocar os trilhos de um dos trens mais rápidos do mundo: o Expresso Pix.