Como integrar seu sistema com o ERP sem dor de cabeça

O pedido chega pelo portal, a equipe comercial confirma no CRM, a produção programa num sistema próprio e o faturamento acontece no ERP. Entre um e outro, alguém copia dados, exporta planilha, confere código de produto e corrige o que não bateu. Todo mundo sabe que isso deveria estar integrado. Quase ninguém sabe exatamente por onde começar.

A boa notícia é que integrar um sistema com o ERP é um problema conhecido, com padrões maduros. A má notícia é que a maior parte das integrações que dão dor de cabeça não falha por falta de tecnologia. Falha por decisões que ninguém tomou antes de escrever a primeira linha de código.

Este texto cobre essas decisões, seja o seu ERP TOTVS, SAP, Omie, Bling ou outro.

Integração é um produto, não um script

O jeito mais comum de começar é também o que mais cobra depois: um desenvolvedor escreve um script que roda de madrugada, lê pedidos de um lado e grava do outro. Funciona na primeira semana. Três meses depois, um pedido some, ninguém sabe se ele chegou a ser enviado, e a única pessoa que entende o script está de férias.

Uma integração que sustenta a operação tem as mesmas necessidades de qualquer outro sistema:

• Um dono. Alguém responde por ela, decide o que muda e é avisado quando ela para.
• Requisitos escritos. Quais dados trafegam, em que direção, com que frequência e o que acontece em cada tipo de erro.
• Testes. Pelo menos para as regras de transformação e para os casos que já deram problema.
• Código versionado e documentado, num repositório que pertence à empresa.
• Uma tela ou relatório de acompanhamento para quem opera, não só para quem desenvolveu.

Tratar a integração como produto não significa torná-la grande. Significa aceitar que ela vai durar anos e ser mantida por quem não a escreveu. Esse é o tipo de decisão que cabe num trabalho de arquitetura de software, antes da escolha de ferramenta.

Fonte da verdade: quem manda em cada dado

Antes de discutir API ou fila, responda para cada informação: qual sistema é o dono dela? O dono é o único lugar onde ela é criada e alterada. Os outros sistemas leem, guardam uma cópia e, se precisarem mudar algo, pedem ao dono.

Parece burocrático, mas evita a pior classe de problema em integração: dois sistemas editando o mesmo dado. O cliente muda o endereço no portal, o financeiro corrige o CNPJ no ERP, e a próxima sincronização apaga uma das alterações sem ninguém perceber.

A decisão costuma ser por entidade, mas às vezes precisa descer ao nível do campo. O cadastro de produto pode pertencer ao ERP (código, NCM, unidade, tributação), enquanto a descrição comercial e as fotos pertencem à plataforma de vendas. Nesse caso, a regra precisa estar escrita campo a campo.

Três perguntas ajudam a decidir:

1. Onde a informação nasce na prática? Não onde deveria nascer, mas onde as pessoas de fato a digitam hoje.
2. Qual sistema tem obrigação legal sobre ela? Tudo que alimenta documento fiscal ou contabilidade tende a ficar com o ERP.
3. Quem precisa alterá-la com mais frequência? Se a área comercial muda preço promocional várias vezes ao dia, obrigá-la a fazer isso no ERP pode não ser realista.

Se a discussão sobre o que fica no ERP e o que fica num sistema próprio ainda está em aberto, ela vem antes desta. Tratamos esse ponto em ERP sob medida ou ERP de mercado.

API, arquivo, banco ou fila: as opções reais

Existem basicamente quatro formas de conversar com um ERP. A escolha depende menos de preferência técnica e mais do que o ERP oferece oficialmente.

API: o caminho preferencial

Os ERPs de mercado mais usados no Brasil oferecem APIs em algum grau, mas a cobertura varia. É comum a API permitir criar pedido e consultar título, mas não expor um cadastro auxiliar que o seu processo usa. Confirme operação por operação antes de assumir que "tem API" resolve.

Arquivo: menos elegante, muitas vezes suficiente

Arquivo é lote, e lote tem atraso. Mas para conciliação, fechamento ou carga de tabela de preços, pode ser a opção mais estável. O cuidado principal é nunca processar um arquivo que ainda está sendo escrito, e validar estrutura e totais antes de gravar.

Banco de dados: com muito cuidado, e de preferência só leitura

Escrever direto nas tabelas do ERP pula as regras que o próprio ERP aplica: validações, cálculo de imposto, auditoria. É o atalho que mais gera problemas silenciosos. Leitura numa réplica, para relatórios, é aceitável em muitos casos. Escrita, quase nunca. Quando o sistema do outro lado não tem nenhuma interface decente, o texto sobre como integrar um sistema legado que não tem API discute alternativas mais seguras.

Fila: o amortecedor entre os dois lados

Mesmo quando a conversa com o ERP é por API, uma fila no meio costuma ajudar. O sistema de origem publica "pedido confirmado" e segue a vida; um processo separado consome a mensagem e chama o ERP. Se o ERP estiver lento ou fora do ar, as mensagens esperam em vez de travar a venda. Provedores como AWS e GCP oferecem filas gerenciadas, e há opções de código aberto.

Mapeamento de cadastros, códigos e tabelas auxiliares

Aqui mora a maior parte do trabalho real, e a parte que mais costuma ser subestimada no orçamento de esforço. Dois sistemas quase nunca falam a mesma língua.

Códigos diferentes para a mesma coisa. O produto é "SKU-4471" na loja e "000123" no ERP. A forma de pagamento é "pix" num lado e um código numérico do outro. Cada uma dessas correspondências precisa de uma tabela de-para mantida por alguém, com regra clara para o que acontece quando surge um código novo que ainda não foi mapeado.

Tabelas auxiliares que ninguém lembra. Condição de pagamento, natureza de operação, centro de custo, transportadora, vendedor, unidade de medida, depósito. Um pedido simples pode depender de uma dúzia delas. Se uma estiver faltando, o ERP recusa o pedido, e a mensagem de erro nem sempre ajuda.

Formatos e regras de validação. CNPJ com ou sem máscara, casas decimais, fuso horário, tamanho máximo de campo, caracteres especiais. O ERP pode aceitar um campo de descrição menor do que o sistema de origem permite e cortar o texto sem avisar.

Carga inicial e sincronização contínua são coisas diferentes. Trazer os cadastros existentes, com limpeza e deduplicação, é um projeto em si. Misturar as duas coisas costuma gerar clientes e produtos duplicados.

Uma prática que ajuda: guardar, em cada registro do sistema próprio, o identificador correspondente no ERP. Isso transforma "procurar o cliente pelo nome" em "consultar pelo código", e elimina uma classe inteira de duplicidades.

Falhas, reprocessamento e idempotência

Toda integração vai falhar: o ERP fica indisponível numa atualização, o certificado expira, um cadastro chega incompleto. A pergunta é o que a integração faz quando isso acontece.

Idempotência: reenviar não pode duplicar

Imagine que o sistema envia um pedido ao ERP, o ERP grava, mas a resposta se perde no caminho. O sistema de origem não sabe se deu certo e tenta de novo. Se nada impedir, o pedido é criado duas vezes, e possivelmente faturado duas vezes.

A proteção é a idempotência: cada operação carrega um identificador único, e o destino (ou uma camada intermediária) reconhece que aquela operação já foi processada. Reenviar vira uma operação segura. Sem isso, qualquer tentativa automática de recuperação é um risco.

Separar erro temporário de erro de dado

• Erro temporário (ERP fora do ar, tempo esgotado, limite de requisições atingido): tentar de novo automaticamente, com intervalos crescentes entre as tentativas.
• Erro de dado (cliente sem CNPJ, produto não mapeado, regra fiscal inválida): tentar de novo não resolve. A mensagem vai para uma área de pendências, com o motivo em linguagem que a operação entende.

Reprocessar sem chamar o desenvolvedor

Corrigido o cadastro, alguém da operação precisa conseguir reenviar a mensagem com um clique. Se cada pendência vira chamado para a equipe técnica, o trabalho manual só mudou de área.

Ordem das operações

Alterar um pedido antes de ele ter sido criado no ERP, ou cancelar antes de confirmar, são situações reais quando as mensagens são assíncronas. A integração precisa saber em que ordem aplicar os eventos de um mesmo registro, ou pelo menos detectar quando algo chegou fora de ordem e segurar para reprocessar.

Monitorar a integração antes que o usuário reclame

O pior jeito de descobrir que a integração parou é o cliente ligar perguntando pela nota fiscal. Monitorar integração exige olhar para o negócio, não só para o servidor.

O que acompanhar, no mínimo:

• Mensagens pendentes e com erro, por tipo, com alerta quando passam de um limite.
• Idade da mensagem mais antiga na fila. Uma fila que não esvazia é sinal de problema, mesmo sem erro explícito.
• Volume esperado. Se numa terça-feira normal chegam centenas de pedidos e hoje chegaram zero até o meio-dia, algo está errado, mesmo que nada tenha dado erro.
• Conferência periódica entre os lados. Contar pedidos do dia na origem e no ERP e comparar. Divergência vira alerta.
• Validade de credenciais e certificados, com aviso antecipado.

Cada mensagem deve carregar um identificador que permita segui-la do sistema de origem até o ERP e de volta. Quando alguém pergunta "o que aconteceu com o pedido tal?", a resposta deveria levar minutos. O texto sobre observabilidade com logs, métricas e traces aprofunda como montar esse acompanhamento.

O que perguntar ao fornecedor do ERP

Antes de dimensionar o trabalho, converse com o fornecedor ou com a consultoria que implantou o ERP. As respostas mudam o tamanho do projeto.

1. Quais operações a API cobre? Peça a documentação e confira, uma a uma, as operações que o seu fluxo precisa.
2. Qual versão está instalada e qual é o plano de atualização? Algumas funcionalidades de API só existem em versões mais recentes.
3. Há limite de requisições? Por minuto, por dia, por usuário. Isso define se a integração pode ser em tempo real ou precisa agrupar operações.
4. Existe ambiente de homologação? Integrar testando em produção é arriscado. Pergunte também se ele tem dados parecidos com os reais.
5. Como funciona a autenticação? Token, usuário técnico, certificado, renovação periódica.
6. O ERP publica eventos ou webhooks? Ou será preciso consultar periodicamente para saber o que mudou?
7. Quais customizações já existem no ambiente? Campos e regras específicas da sua empresa mudam o mapeamento.
8. A integração consome licença? Em alguns modelos, o usuário técnico da integração conta como usuário licenciado.
9. Quem dá suporte quando a API se comporta de forma inesperada? E em quanto tempo.

Um roteiro para começar

1. Liste os fluxos. Pedido, cliente, produto, estoque, nota, título, baixa. Para cada um, a direção e a frequência necessária.
2. Defina o dono de cada dado, por entidade e, quando preciso, por campo.
3. Escolha a forma de comunicação com base no que o ERP oferece oficialmente.
4. Monte as tabelas de-para e a regra para códigos ainda não mapeados.
5. Desenhe o tratamento de erro: o que é tentado de novo, o que vira pendência, quem resolve.
6. Comece por um fluxo só, o de maior dor, e coloque em produção com monitoramento antes de partir para o próximo.
7. Defina os indicadores: tempo entre o evento e o registro no ERP, pendências abertas, divergências na conferência diária, horas de redigitação eliminadas.

Se o fluxo mais crítico da sua empresa é entre o ERP e a loja virtual, o texto sobre integração entre ERP e e-commerce detalha os pontos específicos de estoque, preço e pedido.

Como a Pervian Tech conduz uma integração

Começamos pelo mapa: quais sistemas existem, quem é dono de cada dado, o que o ERP oferece oficialmente e onde a operação sofre hoje. A partir daí, a integração é construída em fases, com diagnóstico, um primeiro fluxo em produção e evolução para os demais, sempre com idempotência, reprocessamento pela operação e monitoramento desde o primeiro dia.

Cada ambiente tem um ERP, uma versão e um conjunto de customizações diferentes. Por isso, o cronograma e o investimento são definidos sob consulta, depois de entender o contexto. Se os seus sistemas ainda conversam por planilha, fale com a gente.