← Projetos  ·  EN

Integrando um app com um ERP que não tem idempotência

Estudo de caso · projeto de estágio na ITNEX · TypeScript, Node.js, PostgreSQL, Docker

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 que decidi

1. Classificar toda resposta em 4 resultados

Olho primeiro o status HTTP e depois o corpo:

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

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 que aprendi

← Projetos