← Projects  ·  PT

Integrating an app with an ERP that has no idempotency

Case study · internship project at ITNEX · TypeScript, Node.js, PostgreSQL, Docker

Context

A multi-warehouse inventory web app had to record every stock movement (reservation, picking, return) in the client's TOTVS Datasul ERP through a REST API. Each user action in the app becomes a call to the ERP.

The problem

Three things made the integration risky:

What I decided

1. Classify every response into 4 outcomes

I look at the HTTP status first and then at the body:

2. When in doubt, stop and call a person

Timeouts, unreadable bodies and redirects go to divergente and are never retried automatically, because the ERP may have applied them. Only a human resends. I prefer a visible, stalled movement over a silent duplicate.

3. A unique mark on every movement

The notes field always carries a movement identifier. If something duplicates or stays uncertain, it can be located in the ERP by that mark and reconciled.

4. Validate before calling the API

The translation from the app to the ERP contract is a pure layer with no I/O. If the data is invalid (no project, item without a numeric code, quantity ≤ 0), the movement becomes divergente without even calling the ERP.

5. A queue that protects itself

6. Security and operating modes

Credentials only go out over HTTPS (or localhost), and redirects are not followed. The app runs in three modes: simulado (simulated), api and desligado (off). An invalid configuration value falls back to desligado, never simulado, so a config mistake can't look like success.

Result

What I learned

← Projects