Integrando um app com um ERP que não tem idempotência
Contexto
Um app web de controle de estoque em vários depósitos precisava registrar cada movimentação (reserva, separação, retorno) no ERP Datasul (TOTVS) do cliente, por API REST. Cada ação do usuário no app vira uma chamada no ERP.
O problema
Três coisas deixavam a integração perigosa:
- O ERP não tem idempotência. Se uma chamada dá timeout, eu não sei se ele efetivou ou não. Repetir pode duplicar a movimentação, e não repetir pode perdê-la.
- O status HTTP não conta a história toda. Erro de negócio chega com HTTP 200 e um campo
errorno corpo. - Dado incompleto passa no app e quebra no ERP, como item sem código numérico, quantidade zero ou remessa sem projeto.
O que decidi
1. Classificar toda resposta em 4 resultados
Olho primeiro o status HTTP e depois o corpo:
confirmado: 2xx sem erro no corpo.rejeitado: erro de negócio. Não repete e desfaz a reserva.falha: problema de infraestrutura (401, 403, 404, 429, 5xx, conexão recusada). É o único caso que repete, com backoff exponencial, jitter de ±20% e respeitando oRetry-After.divergente: resultado incerto.
2. Na dúvida, parar e chamar uma pessoa
Timeout, corpo ilegível ou redirect vão para divergente e nunca são repetidos sozinhos, porque o ERP pode ter efetivado. Só um humano reenvia. Prefiro um movimento parado e visível a um duplicado silencioso.
3. Marca única em cada movimento
O campo de observações sempre leva um identificador do movimento. Se algo duplicar ou ficar incerto, dá para localizar no ERP pela marca e conciliar.
4. Validar antes de chamar a API
A tradução do app para o contrato do ERP é uma camada pura, sem I/O. Se o dado é inválido (sem projeto, item sem código numérico, quantidade ≤ 0), o movimento vira divergente sem nem chamar o ERP.
5. Uma fila que se protege
- Envio em lotes de 20, com lease para dois processos não pegarem o mesmo lote.
- Após 3 falhas seguidas de infraestrutura, o ciclo pausa por 60 s, em vez de gastar tentativa dos movimentos que não têm culpa.
- Máximo de 10 tentativas; acima disso o movimento sai da fila e vai para intervenção humana.
- Concorrência configurável (de 1 a 10, padrão 1), para começar devagar.
6. Segurança e modos de operação
As credenciais só saem por HTTPS (ou localhost), sem seguir redirect. O app roda em três modos: simulado, api e desligado. Um valor de configuração inválido cai em desligado, e nunca em simulado, para um erro de config não parecer sucesso.
Resultado
- O conhecimento sobre o ERP (nomes de campos, códigos, formato do item) fica isolado em um único arquivo puro. Se o ERP muda, mexo num lugar só.
- Esse contrato tem 26 testes automatizados (validações, limites, leitura de respostas com entrada inválida). Quebrei uma regra de propósito para conferir que o teste falha.
- A integração está em ambiente de homologação, ainda não em produção.
O que aprendi
- Quando o sistema do outro lado não oferece garantia, a garantia vira responsabilidade minha, e o desenho precisa assumir a incerteza em vez de escondê-la.
- Deixar explícito o que é suposição (marquei no código o que eu havia inferido de exemplos) evita tratar palpite como contrato.
- Teste de contrato é onde mais compensa começar quando o projeto não tinha nenhum.