Integração com ERP: como funciona na prática

Integração com ERP é a parte do projeto que ninguém estima direito na primeira reunião, porque metade da resposta não está com você: está com o fornecedor do ERP. O escopo do seu lado é previsível — ler produto, mostrar preço, gravar pedido. O escopo do outro lado depende de uma pergunta que a maioria das propostas deixa para descobrir depois, com contrato assinado e prazo prometido: essa API deixa gravar dado, ou só ler?

Este texto trata do caso concreto: um site, uma loja ou um sistema interno conversando com o ERP que já roda na empresa. São quatro fluxos de dados que aparecem em quase todo projeto, quatro modelos técnicos com custos e riscos bem diferentes, e uma lista de perguntas para levar ao fornecedor do ERP antes de qualquer orçamento. Na nossa operação, o projeto que encalha quase sempre encalhou nessa conversa que ninguém teve.

“Tem integração” não significa nada, e todo ERP de mercado diz que tem. O que muda o projeto é o que está atrás da palavra: uma API REST documentada, um webhook, um arquivo que cai numa pasta às três da manhã, ou o endereço do banco com a senha que alguém mandou por e-mail.

Os quatro fluxos que fazem 90% do trabalho

Antes de escolher tecnologia, decida o que trafega e em que direção. Quase todo projeto cabe em quatro fluxos, e cada um tem um dono de dado distinto. Dono do dado é o conceito que evita metade das discussões: é o sistema que tem a última palavra quando os dois discordam.

Produto e preço, do ERP para fora. Código, descrição, unidade, NCM, tabela de preço, condição por cliente. O ERP é o dono, sempre. O que quebra aqui é sutil: produto novo cadastrado no ERP entra na vitrine como linha seca, sem foto e sem texto que venda. A saída é separar campo fiscal de campo comercial e deixar o segundo editável fora do ERP.

Estoque, do ERP para fora e quase em tempo real. É o mais sensível dos quatro, porque erro aqui vira venda que você não entrega. Duas decisões pesam mais que a tecnologia: saldo total ou reservado, um depósito ou vários. Aqui a região muda a resposta. Uma distribuidora com sede em Campinas não promete prazo só para o Cambuí: promete para Paulínia, Sumaré, Indaiatuba e Americana no mesmo anúncio, muitas vezes com carga saindo de galpões diferentes. Se o estoque sincroniza uma vez por dia, às três da manhã, a frase “sai hoje” é aposta em cima do número de ontem. Raio grande pede sincronia por evento, não por agenda — é isso que separa uma loja virtual que aguenta operação real de um catálogo bonito.

Pedido, de fora para o ERP. É o único fluxo que precisa gravar, e por isso é o que decide se o projeto existe. Entram aqui carrinho da loja própria, orçamento aprovado no site, pedido do representante em campo e repasse de marketplace, cada origem com formato de cliente, frete e desconto diferente. Se você vende em mais de um canal, vale entender antes como marketplace e loja própria dividem o mesmo estoque.

Financeiro e nota, do ERP para fora. Status de pagamento, número da NF-e, chave de acesso, código de rastreio. É o fluxo mais esquecido no orçamento e o que mais gera ligação no atendimento. O mesmo status que alimenta a página de acompanhamento serve para a resposta automática no atendimento por WhatsApp Business, e aí o dado precisa estar certo em dois canais.

Quatro modelos de integração, e quando cada um é o certo

API REST, você puxando. Seu sistema pergunta, o ERP responde. É o mais fácil de testar e o padrão nos ERPs em nuvem da última década. O custo escondido é a varredura: para saber o que mudou, você pergunta por tudo, a menos que exista filtro por data de alteração. Pergunte por esse filtro antes de qualquer coisa.

Webhook, o ERP avisando. O ERP dispara uma chamada para o seu endereço quando algo muda. Exige duas coisas que quase sempre faltam no orçamento: um endereço público que responda em menos de dois segundos e uma fila para o que chegar com o servidor fora do ar. O melhor desenho combina os dois modelos — o webhook avisa qual registro mudou, a API busca o detalhe.

Arquivo agendado, o velho EDI que não morreu. CSV, XML ou posicional depositado num SFTP em janela noturna. Parece antiquado e tem uma vantagem que ninguém valoriza até precisar: rastro em disco. Quando o pedido some, existe um arquivo com data e hora para conferir.

Banco ou tabela intermediária. O ERP grava numa tabela de troca, você lê; você grava em outra, uma rotina do ERP consome. Comum em ERP instalado com dez anos de customização. Ler direto é tolerável com réplica e usuário só de leitura. Gravar direto é a decisão que mais estrago causa, porque pula todas as regras que o ERP aplica na tela.

A pergunta que redesenha o projeto: a API grava ou só lê?

Há três degraus por trás da palavra integração, e eles valem mais que qualquer folder. O ERP que lê tudo e grava pedido: projeto previsível, prazo que se cumpre. O que lê tudo e grava quase nada: dá para montar vitrine, mas o pedido entra por outro caminho. E o que só exporta arquivo. O projeto é viável nos três; o que muda é o desenho e o orçamento, e isso precisa estar claro antes da assinatura.

Quando a API só lê, sobram três saídas, todas com preço: digitação manual no ERP, importação por planilha, ou automação de tela, que funciona e quebra na primeira atualização do fornecedor.

Vale fazer a conta da primeira. Oitenta pedidos por dia útil, 90 segundos de digitação em cada um, dá duas horas por dia e cerca de 44 horas por mês. A R$ 25 por hora carregada, são R$ 1.100 por mês e R$ 13.200 no ano, sem contar o erro de digitação, que aparece como devolução e nota corrigida. Uma integração de quatro fluxos na faixa de R$ 18.000 se paga em pouco mais de um ano nesse volume. Abaixo de vinte pedidos por dia, quase nunca se paga — e dizer isso é parte do trabalho.

Há ainda o caminho do meio: o plugin de integração pronto. Resolve quando cobre 100% do fluxo, e vira armadilha quando cobre 80% e os 20% restantes são a sua regra de negócio. É a mesma fronteira que separa site montado em plataforma de site escrito em código: quando a regra de negócio mora no site, ele virou software feito para a sua operação.

As perguntas para fazer ao fornecedor do ERP antes de orçar

Leve estas doze por escrito, e peça resposta por escrito. Elas custam uma reunião e evitam o projeto que arrasta seis meses.

1. A API grava pedido ou só lê dados? Peça o nome do endpoint, não a palavra sim.
2. Existe ambiente de homologação separado da produção? Quem libera o acesso, e em quantos dias?
3. Qual o limite de requisições por minuto e por dia? E o que acontece ao estourar: fila, erro ou bloqueio da chave.
4. Existe endpoint de lote para produto e estoque, ou a consulta é item a item?
5. Existe webhook? Para quais eventos, e com repetição automática quando o meu servidor não responde?
6. A documentação é pública? Peça o link antes da reunião. A que só existe em PDF por e-mail costuma estar desatualizada.
7. Todos os campos da tela estão na API? Peça uma resposta real, com dados, do objeto de pedido e do de produto.
8. Como a API identifica um pedido que já entrou? Existe campo de número externo ou chave de idempotência?
9. Quem paga a licença de integração? Muitos ERPs cobram por módulo, por conexão ativa ou por volume de chamadas.
10. Qual o SLA e a janela de manutenção? Se o ERP para de madrugada para rotina, o site precisa saber o que fazer nesse intervalo.
11. Que versão o cliente roda hoje, e a API existe nessa versão? Recurso documentado na versão nova não ajuda quem está três atualizações atrás.
12. Quem responde, com nome e telefone, quando a integração parar às 9h de uma segunda-feira?

A número 2 é a que mais atrasa cronograma em Campinas, onde muita indústria, laboratório e operador logístico roda ERP instalado com anos de customização e time de TI próprio. A homologação existe, mas liberar acesso a fornecedor externo passa por aprovação interna que ninguém contou no prazo. Pergunte no primeiro dia, não no dia de testar.

Idempotência, ou o pedido que entra duas vezes

Este é o defeito mais caro de uma integração e o menos discutido nas propostas. A sequência é sempre a mesma: seu sistema envia o pedido, o ERP cria o registro, e a resposta se perde no caminho — tempo esgotado no gateway, queda de rede, reinício do servidor. Seu sistema, sem confirmação, tenta de novo. O ERP cria um segundo pedido idêntico.

O estrago não fica no banco de dados. São duas separações no estoque, duas notas emitidas, duas cargas saindo, um cliente cobrado uma vez só e um estorno para fazer. Com nota fiscal eletrônica, cancelar sai mais caro que o pedido.

A proteção tem três camadas, baratas quando entram no desenho desde o início. A chave de idempotência: um identificador único gerado pelo seu lado, que faz o ERP devolver o pedido original em vez de criar outro. O número de pedido externo com restrição de unicidade, que faz a segunda tentativa ser recusada pelo próprio banco — e essa recusa é boa notícia. E a reconciliação: rotina diária que compara os dois sistemas e lista as diferenças numa tela que alguém abre de manhã.

A regra prática: toda chamada que grava precisa de chave de idempotência, repetição com intervalo crescente e fila para o que falhou. Toda chamada que só lê pode ser repetida à vontade. Confundir as duas é como nasce o pedido duplicado.

Os erros que mais vemos

Aceitar “tem integração” como resposta. É a origem de quase todo projeto que encalha: a palavra cobre desde uma API completa até um exportador de CSV manual. Só o nome do endpoint encerra a dúvida.

Começar sem ambiente de homologação. Testar gravação em produção significa criar pedido de mentira no ERP da empresa, com número de nota queimado e estoque movimentado. Já perdemos projeto por insistir em homologação antes de assinar, e continuamos insistindo.

Escrever direto nas tabelas do ERP. A tela aplica dezenas de regras que a tabela não conhece: validação fiscal, limite de crédito, reserva de saldo, numeração. Gravar por fora produz registro que o próprio ERP considera inválido, e a descoberta acontece no fechamento contábil.

Tratar o campo da tela como se existisse na API. Acontece com campo customizado, que é justamente o que a empresa mais usa. Peça uma resposta real e confira campo a campo contra a tela antes de estimar: dez minutos que evitam uma semana perdida.

Ignorar o limite de requisições até o dia de pico. No dia comum a cota sobra. Na campanha o volume triplica, a chave é bloqueada e o estoque congela na hora errada. Meça pelo pior cenário previsto, não pela média.

Não construir tela de erro. Integração que falha em silêncio é pior do que integração que não existe, porque a empresa decide em cima de número errado. Toda integração precisa de fila de reprocessamento e de uma tela onde alguém não técnico veja o que travou e mande tentar de novo.

O próximo passo não é pedir orçamento. É marcar trinta minutos com quem dá suporte ao seu ERP, levar as doze perguntas e voltar com três respostas por escrito: o endpoint que grava pedido, o limite de requisições e a data em que a homologação estará liberada. Com esses três dados qualquer proposta vira comparável, e quem orça sem eles está chutando. Antes dessa decisão, os artigos sobre sistemas sob medida cobrem comprar ou construir, recorte da primeira versão e a conta de manter o software vivo.