Arquitetura · Integrações · Critérios de aceite

Idempotência em integrações ERP: repetir a mensagem sem repetir a operação

Por Jeferson Resende · 9 de novembro de 2026 · Laboratório autoral com dados fictícios

O consumidor salvou o envio de um pedido. Antes de confirmar a mensagem ao transporte, o processo caiu. Na nova tentativa, o mesmo evento chegou outra vez. O sistema precisa reconhecer o resultado já confirmado.

O problema começa depois do caminho feliz

Em uma integração entre ERP e expedição, uma mensagem repetida pode gerar uma segunda ordem, repetir uma reserva ou produzir uma divergência operacional. Antes de escolher uma ferramenta, defina o efeito que deve acontecer uma única vez e o identificador que permite reconhecer sua repetição.

Este projeto usa três bancos SQLite separados: ERP fictício, transporte local e consumidor. Ele demonstra uma decisão de arquitetura e seus testes. Não acessa SAP, SQS, sistemas de clientes ou dados de produção.

A decisão: confirmar o efeito e a deduplicação juntos

O consumidor usa a chave (consumer, event_id). O mesmo ID com conteúdo diferente é um conflito; não pode desaparecer silenciosamente como se fosse uma repetição normal. Por isso, o laboratório também compara um fingerprint do payload.

1. Abrir uma transação local e verificar a identidade do evento.
2. Validar a versão do pedido e as regras de estado.
3. Gravar estado, efeito local e resultado de processamento na mesma transação.
4. Confirmar a mensagem ao transporte somente depois do commit.

Falha antes do commit reverte tudo. Falha depois do commit e antes do ACK deixa o resultado persistido: a nova tentativa encontra a inbox e retorna duplicate, sem repetir o efeito. O teste de reinício usa um processo Python separado, não apenas um conjunto em memória.

Por que existe uma outbox na origem?

O ERP fictício grava a mudança do pedido e a intenção de publicar o evento juntos. O relay entrega ao transporte e depois marca a outbox. Se cair entre esses passos, pode entregar novamente. A outbox trata a janela de perda na origem; a idempotência continua necessária no consumidor.

E as mensagens fora de ordem?

Neste cenário, uma versão antiga é registrada como stale, sem regredir o pedido. Uma versão futura com lacuna exige recuperar a dependência e tentar novamente. Cancelamento é terminal. Essas políticas são explícitas e testadas, mas devem ser definidas com o negócio em cada integração.

O que foi executado

14 testes automatizados passaram no ambiente de desenvolvimento. O resultado não mede desempenho, disponibilidade nem economia em clientes. A revisão externa permanece pendente.

A demonstração termina com três efeitos de negócio locais: criação, envio e cancelamento. O envio aparece uma vez, apesar das duas tentativas de entrega. Confira o JSON gerado pela execução e os testes completos.

Reproduza sem conta paga

Use Python 3.10 ou superior. Não é necessário instalar pacotes externos. Na pasta do projeto:

python -m unittest discover -s tests -v
python lab.py demo --output evidence/minha-execucao.json

Para inspecionar os bancos, use python lab.py demo --directory .runtime. O README explica a limpeza restrita dos arquivos gerados e os resultados esperados. O exemplo usa somente dados inventados.

Onde esta demonstração termina

• O efeito protegido está no mesmo banco da inbox. Uma chamada HTTP, pagamento ou e-mail externo exige estratégia própria.
• O transporte local não reproduz toda a semântica de um broker real, rede ou ambiente distribuído.
• SQLite serializa a escrita. O teste local não comprova escala, SLA ou compatibilidade direta com SAP.
• Retenção de deduplicação, observabilidade, autenticação e recuperação operacional precisam ser projetadas para produção.
• Não há promessa de exactly-once de ponta a ponta, homologação de cliente ou revisão independente concluída.

O papel da liderança técnica nessa conversa

A decisão precisa ser compreendida por quem desenvolve, testa e opera. O Tech Lead explicita o efeito protegido, a janela de falha e o limite da evidência; gestão do projeto coordena dependências; operação e responsáveis de negócio definem o aceite. Um teste de caminho feliz não encerra essa discussão.

Continue a leitura

• Gestão de dependências em projetos de TI
• O papel do Tech Lead entre arquitetura, projetos e negócio
• Conversar sobre arquitetura e entregas no LinkedIn

Referências técnicas

• AWS: Transactional outbox pattern
• Microsoft: Idempotent Consumer
• SQLite: Transactions

Laboratório autoral desenvolvido com assistência de IA e testes automatizados. Exemplos fictícios; não representa AtisWork, CPFL Energia ou clientes. Última revisão: 9 de novembro de 2026.