O guia definitivo para integrar APIs REST no seu ERP

Integração de API com ERP tem fama de projeto difícil, mas quase nunca falha pelo motivo que as pessoas esperam. Raramente é o protocolo, o formato do payload ou a autenticação — isso está documentado e resolve em uma tarde. O que derruba integração em produção é sempre a mesma lista curta de decisões que ninguém tomou de propósito.

Este guia é essa lista, na ordem em que ela costuma aparecer.

Antes de escrever código: onde a chamada mora

A primeira decisão define todas as outras, e é a que mais gente pula.

Uma chamada de API pode acontecer em três lugares, e eles têm consequências completamente diferentes:

No caminho do usuário — alguém digita um CNPJ no formulário de cadastro e espera os campos preencherem. A chamada é síncrona, o usuário está olhando, e cada milissegundo importa. Aqui, indisponibilidade da API precisa degradar com elegância: se a consulta falhar, o formulário continua funcionando com preenchimento manual. Uma integração que trava o cadastro quando o serviço externo cai é pior do que não ter integração.

Em segundo plano, por evento — um pedido foi criado e você quer enriquecer os dados do cliente. Ninguém está esperando. Aqui a chamada vai para uma fila, pode levar segundos, pode tentar de novo, e a falha não bloqueia nada.

Em lote, agendado — toda madrugada você revalida a situação cadastral da carteira inteira. Volume alto, tolerância a lentidão alta, mas exige atenção a limite de requisições.

A maioria dos problemas de integração vem de tratar um desses casos com o código do outro. Consulta em lote rodando de forma síncrona dentro de um request HTTP é a receita mais comum de timeout em produção.

O ERP raramente aceita chamada externa direta

Aqui vem o obstáculo prático. ERPs — especialmente os consolidados, com anos de customização — costumam viver em rede fechada, com linguagem própria, ciclo de release trimestral e um DBA que precisa aprovar cada alteração. Colocar um cliente HTTP dentro do ERP costuma ser mais caro politicamente do que tecnicamente.

O padrão que funciona é não colocar. Em vez disso, construa uma camada intermediária — um serviço pequeno, na sua stack preferida, que fala com a API externa e expõe para o ERP algo que ele já sabe consumir: uma tabela, uma view, um endpoint interno, um arquivo em diretório compartilhado.

Isso resolve três problemas de uma vez. O ERP não precisa de acesso à internet. A lógica de retry, cache e tratamento de erro fica em código que você consegue alterar sem passar por comitê. E quando a API mudar de versão, você mexe em um serviço, não no núcleo do sistema que a empresa inteira usa.

Cache não é otimização, é requisito

Muita gente trata cache como refinamento para depois. Em integração com dados cadastrais, ele é obrigatório desde o primeiro dia — e por um motivo que não é performance.

Dados de CNPJ mudam devagar. A base oficial é atualizada em ciclos de semanas. Consultar o mesmo CNPJ quarenta vezes no mesmo dia não traz nenhuma informação nova; só gasta quota, aumenta latência e cria dependência desnecessária de um serviço externo.

A regra prática: guarde a resposta com a data da consulta e trate como válida por um período compatível com o ciclo de atualização da fonte. Para dados cadastrais de empresa, algo entre sete e trinta dias é razoável. Guarde a resposta inteira, não só os campos que você usa hoje — o custo de armazenamento é irrelevante e o campo que você descartou é sempre o que alguém vai precisar no trimestre seguinte.

A exceção importante são as decisões em que o dado precisa ser o de agora, não o de duas semanas atrás: aprovar um limite de crédito, aceitar um fornecedor novo, assinar contrato. Nesses pontos vale furar o cache deliberadamente e fazer uma consulta em tempo real, e registrar no log que aquela decisão específica foi tomada com dado do momento. É a diferença entre uma auditoria tranquila e uma conversa difícil.

E guarde também as consultas que não retornaram nada. Um CNPJ inexistente continua inexistente na próxima tentativa; sem cache negativo, um dado ruim na base vira uma chamada perdida por dia, para sempre.

Timeout, retry e o erro clássico

Toda chamada externa precisa de timeout explícito. Sem ele, o cliente HTTP usa o padrão da biblioteca, que costuma ser generoso demais ou infinito — e uma única chamada travada segura uma conexão, que segura uma thread, que eventualmente derruba o pool inteiro.

Defina o timeout a partir do contexto: se o usuário está esperando, poucos segundos; se é processamento em fila, mais folga.

Para retry, três regras que evitam a maior parte dos incidentes:

Só repita o que faz sentido repetir. Erros de rede, timeout e respostas 5xx são candidatos. Um 400 significa que sua requisição está errada — repetir vai dar 400 de novo. Um 401 significa credencial inválida; repetir só acelera o bloqueio. Um 429 significa que você passou do limite, e aí a resposta correta é esperar, não insistir.

Espere de forma crescente. Retry imediato em rajada é como a maioria das integrações transforma uma instabilidade momentânea do fornecedor em uma indisponibilidade prolongada. Dobre o intervalo a cada tentativa e adicione uma variação aleatória, para que mil clientes não voltem todos no mesmo instante.

Tenha um teto. Três tentativas e desista, registrando a falha de forma recuperável. Retry infinito não é resiliência; é uma fila que cresce até estourar.

Idempotência, no lugar certo

Consulta é naturalmente idempotente — perguntar duas vezes pelo mesmo CNPJ não causa dano. O cuidado com idempotência aparece do seu lado da integração, no que você faz com a resposta.

Se o retorno da consulta dispara a criação de um registro no ERP, e o retry acontece depois de a primeira chamada ter sido processada mas antes de a confirmação chegar, você cria o registro duas vezes. A proteção é ter uma chave de negócio única — o próprio CNPJ, normalmente — e escrever com "insere ou atualiza" em vez de "insere".

Parece óbvio escrito assim. Ainda assim é a origem de boa parte dos cadastros duplicados que times de dados passam meses limpando.

Log do que você vai precisar às três da manhã

O log de integração tem um público específico: a pessoa que vai investigar por que um cliente reclamou que o cadastro veio errado, seis semanas depois de ter acontecido.

Registre, para cada chamada: o identificador consultado, o horário, o código de status, o tempo de resposta e um identificador de correlação que amarre a chamada ao request de origem. Em caso de erro, registre o corpo da resposta.

Não registre a chave de API. Nunca. É a forma mais comum de vazamento de credencial: alguém loga o cabeçalho inteiro para depurar, esquece de tirar, e a chave passa a viver em texto puro num sistema de log com acesso amplo.

E cuidado com dados pessoais. Log de integração costuma ficar fora do inventário de tratamento de dados da empresa — e é exatamente o tipo de coisa que aparece numa auditoria de LGPD. Registre o CNPJ consultado; pense duas vezes antes de registrar a resposta inteira com nomes de sócios.

O monitoramento que vale a pena

Um alerta que dispara toda semana por ruído é ignorado em duas semanas. Comece com três métricas e resista à tentação de adicionar mais antes de precisar:

Taxa de erro por status, separando 4xx de 5xx — a diferença entre "estou chamando errado" e "o fornecedor está com problema". Latência no percentil 95, porque a média esconde a cauda que os usuários realmente sentem. E taxa de acerto do cache: se ela cair de repente, algo mudou no padrão de uso e a sua conta vai refletir isso antes de você perceber.

Um roteiro de implantação

Do que costuma dar certo, em ordem:

Comece pelo caso de uso mais estreito que já entrega valor — normalmente o preenchimento automático de um formulário de cadastro. É visível, mede fácil e não põe processo crítico em risco.

Rode em modo sombra antes de confiar. Faça a chamada, registre o resultado, mas não use ainda. Uma semana disso mostra a taxa real de erro e de resposta vazia com dados de produção, sem consequência.

Só depois ligue de verdade, e mantenha o caminho manual funcionando. Integração que remove a alternativa manual antes de provar estabilidade cria um ponto único de falha com cara de melhoria.

Amplie para os outros casos de uso reaproveitando a mesma camada intermediária. O segundo caso deve custar uma fração do primeiro — se não custar, a camada foi mal desenhada e vale corrigir antes do terceiro.

---

Se o dado que você precisa integrar é cadastro de empresa brasileira, a Next API resolve CNPJ, CNAE, CEP e geolocalização por REST, com base sincronizada para volume e consulta em tempo real para as decisões que não podem errar. E se a integração fizer parte de um projeto maior, a Sharpfy também constrói sob medida — inclusive a camada intermediária descrita aqui.