Como integrar ERP e e-commerce

Quando ERP e e-commerce trabalham isoladamente, a equipe frequentemente precisa copiar pedidos, produtos, estoque, preços e dados de clientes entre sistemas.

Além do tempo gasto, processos manuais aumentam o risco de inconsistências.

Uma integração permite automatizar esse fluxo, mas precisa definir claramente qual sistema é responsável por cada informação.

Comece pelo fluxo, não pela API

Antes de desenvolver, desenhe o processo.

Perguntas importantes:

onde produtos são cadastrados?
quem controla preço?
qual sistema é responsável pelo estoque?
onde o pedido nasce?
quando o ERP deve receber o pedido?
como o status retorna ao e-commerce?
cancelamentos precisam sincronizar?
notas fiscais participam do fluxo?

Sem essas respostas, é possível construir uma integração tecnicamente funcional que não representa corretamente a operação.

Defina a fonte de verdade

Para cada dado, deve existir um sistema principal.

Por exemplo:

ERP pode ser responsável por estoque;
e-commerce pode originar pedidos;
ERP pode controlar faturamento;
plataforma de vendas pode exibir status ao cliente.

Evite permitir alterações concorrentes sem regras claras.

API e webhooks

APIs permitem consultar ou alterar informações entre sistemas.

Webhooks permitem que uma plataforma avise outra quando um evento acontece.

Quando disponíveis, podem ser combinados.

Exemplo: o e-commerce envia um webhook quando existe novo pedido e a integração utiliza a API para buscar detalhes necessários.

Integrações falham

Serviços ficam indisponíveis. Internet falha. APIs limitam requisições. Dados chegam incompletos.

A arquitetura precisa prever:

logs;
tentativas;
idempotência;
filas quando necessário;
alertas;
reprocessamento;
tratamento de erros.

Uma falha não pode simplesmente desaparecer.

Evite pedidos duplicados

Um dos problemas clássicos acontece quando uma requisição é reenviada depois de um timeout.

O sistema precisa reconhecer se aquela operação já foi processada.

Esse conceito é conhecido como idempotência e é especialmente importante em pedidos, pagamentos e outras operações críticas.

Sincronização de estoque merece atenção especial

Estoque muda rapidamente.

Defina:

frequência;
reserva;
cancelamento;
múltiplos depósitos;
kits;
variações;
concorrência de vendas.

Não existe uma estratégia única adequada a todos os negócios.

Segurança

Credenciais de API não devem ficar expostas no frontend.

A integração deve usar autenticação adequada, conexões seguras e permissões limitadas ao necessário.

Logs também precisam evitar exposição indevida de informações sensíveis.

Monitoramento

Depois da implantação, acompanhe o fluxo.

Uma integração que “não deu erro” não significa necessariamente que está processando tudo.

Métricas como quantidade de eventos recebidos, processados, com erro e pendentes ajudam a enxergar a operação.

Conclusão

Integrar ERP e e-commerce é um projeto de processo e dados tanto quanto de programação.

Quanto mais clara a responsabilidade de cada sistema, mais simples é construir uma integração confiável.

Sua equipe ainda transfere informações manualmente entre sistemas?

A Jumps desenvolve integrações e APIs para conectar plataformas e automatizar operações.

Falar sobre uma integração →

Relacionado: Integrações e APIs.

Integração entre ERP e e-commerce: erros comuns e como evitar

A integração entre o ERP e a plataforma de e-commerce é o que sustenta a operação de venda online: o estoque que aparece no site vem do ERP, o pedido que o cliente faz precisa chegar na expedição, o preço e a promoção precisam estar consistentes nos dois lados. Quando essa integração falha, o cliente compra o que não existe, o pedido some entre os sistemas ou a nota fiscal sai errada.

A maioria dos problemas não aparece no dia a dia calmo — aparece no pico, na Black Friday, quando o volume multiplica e as falhas que estavam latentes viram incidente. Este artigo lista os erros mais comuns e o que os previne.

Erro 1: sincronizar só por horário fixo

Uma integração que roda “de hora em hora” deixa o estoque desatualizado durante todo o intervalo. Em um produto que vende rápido, isso significa vender unidades que já não existem, gerando cancelamento, reembolso e cliente insatisfeito. No pico, o intervalo fica ainda mais perigoso.

O ideal é reagir a eventos: quando uma venda acontece no site, o ERP é atualizado na hora; quando o estoque muda no ERP (uma entrada, um ajuste, uma venda em outro canal), o site é notificado. A sincronização por horário serve como rede de segurança para reconciliar, não como mecanismo principal.

Erro 2: não tratar as falhas

Toda chamada entre sistemas pode falhar — o ERP está fora, a rede caiu, a resposta demorou demais. Se a integração não trata isso, o pedido que não foi transmitido simplesmente desaparece, e ninguém percebe até o cliente reclamar que não recebeu.

O que resolve: uma fila entre os sistemas, onde cada operação fica registrada até ser confirmada; novas tentativas automáticas com espaçamento crescente; e um alerta quando algo falha repetidamente. Nada pode se perder silenciosamente.

Erro 3: assumir que o ERP aguenta a carga

O ERP foi dimensionado para a operação interna — alguns usuários, um ritmo previsível. Um e-commerce em promoção pode gerar centenas de pedidos por minuto e milhares de consultas de estoque. Jogar essa carga direto no ERP costuma derrubá-lo, e com ele a operação inteira.

A solução é colocar uma camada no meio: um serviço de integração que mantém uma cópia do estoque e do catálogo para servir o site rapidamente, e que envia para o ERP em um ritmo que ele suporta, enfileirando quando necessário.

Erro 4: falta de idempotência

Idempotência é a propriedade de uma operação poder ser executada várias vezes com o mesmo efeito de uma vez só. Sem ela, uma nova tentativa de enviar um pedido que na verdade já tinha sido recebido cria um pedido duplicado — e a expedição manda o produto duas vezes.

Cada operação precisa carregar um identificador único, e o sistema receptor precisa reconhecer quando já processou aquele identificador e ignorar a repetição. É um detalhe técnico que evita um tipo de erro caro e difícil de rastrear.

Erro 5: não registrar o que foi sincronizado

Quando o estoque do site e o do ERP divergem — e uma hora divergem —, é preciso conseguir auditar: o que foi enviado, quando, com qual resposta. Sem esse registro, a reconciliação vira adivinhação e o problema se repete.

Um log estruturado de cada operação de integração, com data, conteúdo e resultado, é barato de manter e paga-se na primeira investigação de divergência.

Erro 6: mapeamento de dados frágil

ERP e e-commerce descrevem as mesmas coisas de formas diferentes: código de produto, unidade de medida, categoria fiscal, forma de pagamento, status de pedido. Um mapeamento feito às pressas quebra quando surge um produto com uma variação nova ou uma condição de pagamento que não estava prevista.

O mapeamento precisa ser explícito, documentado e ter um comportamento definido para o caso não previsto — parar e alertar, em vez de adivinhar e seguir.

Erro 7: ignorar os outros canais

Muitas operações vendem em mais de um lugar — a loja própria, marketplaces, uma força de vendas. Se cada canal integra com o ERP de forma isolada, o estoque vira uma disputa: dois canais vendem a última unidade ao mesmo tempo. Uma camada central de gestão de estoque, que todos os canais consultam e atualizam, resolve.

O que dá estabilidade a uma integração de e-commerce

Reação a eventos como mecanismo principal, com sincronização periódica como reconciliação.
Fila entre os sistemas, com novas tentativas e alertas.
Camada intermediária que protege o ERP da carga do site.
Idempotência em todas as operações que criam ou alteram dados.
Log estruturado de tudo que trafega.
Mapeamento de dados explícito, com tratamento definido para o caso não previsto.
Um painel simples para a operação ver o que passou e o que ficou preso.
Testes de carga antes das datas de pico.

Preparação para datas de pico

Antes de Black Friday, Natal ou uma campanha grande, vale um roteiro: simular o volume esperado, verificar se a fila e a camada intermediária aguentam, confirmar que os alertas estão funcionando e que alguém vai estar de plantão, e ter um plano para o caso de o ERP ficar indisponível — o site pode continuar vendendo com a integração enfileirando, e reconciliar depois.

O que sincronizar além de estoque e pedido

A integração estoque-pedido é a mais visível, mas uma operação completa costuma precisar sincronizar mais:

Catálogo — cadastro de produtos, descrições, atributos, imagens, geridos no ERP ou em um PIM e publicados no site.
Preços e promoções — tabelas por canal, por cliente, por data, com regras que precisam ser consistentes.
Clientes — dados cadastrais, histórico, limite de crédito, para não ter dois cadastros do mesmo cliente.
Status logístico — nota fiscal emitida, pedido faturado, código de rastreio, entregue, devolvido — para o cliente acompanhar e o SAC responder.
Financeiro — conciliação de pagamentos, estornos, antifraude.

Cada um desses fluxos tem sua direção (quem é a fonte da verdade) e sua frequência. Definir isso de forma explícita, em um documento, evita a maior parte das divergências.

Reconciliação: aceitar que vai divergir

Nenhuma integração é perfeita o tempo todo. Uma chamada perdida, um sistema fora do ar por minutos, um erro de mapeamento — e os dois lados divergem. O que separa uma operação estável de uma caótica não é nunca divergir, é detectar e corrigir rápido.

Um processo de reconciliação periódica — comparar o estoque dos dois lados, identificar pedidos sem correspondência, apontar divergências de preço — roda automaticamente e gera uma lista curta para a operação resolver. Sem ele, as divergências se acumulam até virar um problema grande.

Middleware pronto ou integração sob medida

Existem plataformas de integração (hubs, iPaaS, conectores prontos) que ligam ERPs e e-commerces populares com configuração mínima. Para operações padronizadas, com sistemas comuns e regras simples, elas entregam valor rápido e barato. Vale sempre avaliá-las primeiro.

A integração sob medida se justifica quando há um ERP customizado ou legado, regras de negócio específicas (tabelas de preço complexas, reservas de estoque, políticas por canal), volume que exige controle fino de performance, ou a necessidade de orquestrar mais de dois sistemas. Nesses casos, o conector pronto ou não cobre, ou cobre com gambiarras que custam mais do que uma solução própria.

Quem é dono da integração

Um problema recorrente é a integração não ter dono. O fornecedor do e-commerce aponta para o do ERP, que aponta de volta. Quando algo quebra, ninguém assume. Definir explicitamente quem é responsável pela camada de integração — construir, monitorar, corrigir — e dar a essa pessoa ou fornecedor acesso e visibilidade dos dois lados é o que evita que um pedido perdido fique dias sem solução.

Como a Jumps implementa

A Jumps implementa integrações entre ERP, e-commerce e demais sistemas com esse conjunto de cuidados: arquitetura orientada a eventos, fila com reprocessamento, camada de proteção do ERP, idempotência e observabilidade. O objetivo é que o pico de vendas seja um evento comercial, não um evento de infraestrutura.

Se a sua integração entre loja e ERP dá sustos, especialmente perto das datas de maior volume, fale com a Jumps.

APIs internas: como documentar, versionar e monitorar bem

Toda empresa com mais de um sistema tem APIs internas, mesmo que ninguém as chame assim: o jeito que o site fala com o backend, que o app consome os dados, que o sistema de faturamento pega informação do cadastro. Quando essas interfaces são tratadas como detalhe de implementação, elas se tornam frágeis, indocumentadas e uma fonte constante de atrito entre times e entre fornecedores.

Tratar APIs internas como produto — com contrato claro, documentação e acompanhamento — reduz esse atrito e torna o ecossistema mais fácil de evoluir. Este artigo cobre os três pilares: documentação, versionamento e monitoramento.

O contrato é o produto

Uma API é, essencialmente, uma promessa: “se você me chamar assim, eu respondo assado”. Esse contrato — os endpoints, os parâmetros, os formatos, os códigos de erro — é o que os outros sistemas dependem. Quebrar o contrato sem aviso quebra quem consome.

O primeiro passo para tratar a API bem é tornar esse contrato explícito e verificável, não algo que só existe no código e na memória de quem escreveu.

Documentação que não desatualiza

Documentação de API mantida à mão sempre desatualiza — alguém muda o código e esquece de atualizar o texto. A forma de evitar isso é gerar a documentação a partir de uma fonte única, verificada contra o código:

Especificação OpenAPI (antigo Swagger) — descreve a API em um formato estruturado que serve para gerar documentação navegável, clientes em várias linguagens e testes de contrato.
Testes de contrato — verificam automaticamente que a API real corresponde à especificação; se alguém muda o código sem atualizar o contrato, o teste falha.
Exemplos reais — requisições e respostas de verdade, não pseudocódigo, para quem vai integrar.
Changelog — o que mudou em cada versão, em linguagem de quem consome.

A documentação boa responde não só “o que a API faz”, mas “como começo a usar”, “o que fazer quando dá erro” e “o que mudou recentemente”.

Versionamento: mudança compatível e incompatível

Nem toda mudança precisa de uma versão nova. A distinção:

Compatível — adicionar um campo opcional na resposta, um parâmetro opcional, um novo endpoint. Quem já consome continua funcionando. Não precisa de nova versão.
Incompatível — remover ou renomear um campo, mudar um formato, tornar obrigatório algo que era opcional, mudar um comportamento. Quebra quem consome. Precisa de nova versão.

Para mudanças incompatíveis, a prática é publicar a nova versão e manter a antiga funcionando por um período de transição definido, com uma data de descontinuação comunicada com antecedência. Ninguém deve descobrir que a API mudou porque o sistema parou.

Como versionar na prática

Versão no caminho da URL (/v1/, /v2/) — simples e visível, a mais comum para APIs internas.
Versão no cabeçalho — mais limpa na URL, menos óbvia.
Evolução sem versão — só mudanças compatíveis, com campos antigos marcados como obsoletos antes de sumir; exige disciplina.

Para a maioria dos casos internos, a versão na URL combinada com uma política clara de compatibilidade resolve bem.

Monitoramento: o que medir

Uma API interna sem monitoramento é um ponto cego: o time só descobre que ela está lenta ou com erro quando o usuário final reclama de um sintoma distante. O básico a acompanhar, por endpoint:

Latência — tempo de resposta, olhando as médias e principalmente os piores casos (percentil 95 e 99).
Taxa de erro — proporção de respostas com erro, separando erro do cliente (4xx) de erro do servidor (5xx).
Volume — requisições por minuto, para entender carga e detectar picos anômalos.
Saturação — uso de recursos que limita a capacidade (conexões de banco, memória, fila).

Com esses dados, dá para definir alertas úteis: latência acima de um limite, taxa de erro subindo, volume fora do padrão. E dá para planejar capacidade antes de o problema aparecer.

Autenticação e limites entre sistemas internos

Mesmo “interna”, uma API precisa saber quem está chamando. Autenticação entre serviços — tokens, chaves, certificados — permite auditar o uso, revogar acesso e aplicar limites por consumidor. Limites de taxa protegem a API de um sistema com defeito que entra em laço e dispara milhares de chamadas, derrubando o serviço para todos os outros.

Erros: um formato consistente

APIs que retornam erros de formatos diferentes em situações diferentes são um pesadelo para quem integra. Defina um formato único de erro — um código, uma mensagem legível, um identificador para rastrear no log — e use-o em toda a API. Quem consome consegue tratar erros de forma genérica, e o suporte consegue investigar um caso específico pelo identificador.

APIs e fornecedores

Quando parte do ecossistema é mantida por fornecedores diferentes, as APIs internas viram a fronteira contratual entre eles. Definir e documentar esses contratos, com testes automatizados que verificam a conformidade, evita a discussão de “o problema é do seu lado ou do meu” e torna possível trocar de fornecedor de um módulo sem reescrever quem depende dele.

Ambientes: produção, homologação e testes

Quem consome uma API interna precisa de um lugar seguro para desenvolver e testar sem afetar a produção nem os dados reais. Um ambiente de homologação estável, com dados de teste realistas e a mesma versão da API que vai para produção, reduz o atrito de integração e o número de incidentes causados por “funcionou no meu teste”.

Vale também oferecer uma coleção de exemplos executáveis — no Postman, Insomnia ou equivalente — para que quem vai integrar comece rápido, sem decifrar a documentação do zero.

Design que envelhece bem

Algumas decisões de design tornam a API mais fácil de evoluir sem quebrar:

Retornar objetos, não valores soltos, para que campos novos possam ser adicionados sem mudar a estrutura.
Usar nomes claros e estáveis; renomear é sempre uma mudança incompatível.
Paginar coleções desde o início, mesmo que hoje sejam pequenas.
Aceitar campos desconhecidos sem falhar, para tolerar clientes de versões diferentes.
Datar e versionar formatos de data e número explicitamente.

Governança leve

Empresas com muitas APIs internas acabam precisando de um mínimo de governança — não um comitê pesado, mas um conjunto de convenções compartilhadas: como nomear endpoints, qual o formato de erro, como versionar, onde publicar a documentação. Um guia curto de estilo de API, seguido por todos os times e fornecedores, faz o ecossistema inteiro ficar mais previsível.

REST, GraphQL ou mensageria

Nem toda integração interna precisa ser uma API REST. As opções principais e quando cada uma cabe:

REST — o padrão para a maioria dos casos: simples, cacheável, bem suportado, fácil de depurar.
GraphQL — útil quando muitos consumidores diferentes precisam de recortes diferentes dos mesmos dados, evitando criar dezenas de endpoints específicos. Adiciona complexidade de servidor e de cache.
Mensageria / eventos — quando a comunicação é assíncrona por natureza: “um pedido foi criado” e vários sistemas reagem. Desacopla os sistemas e absorve picos, ao custo de um broker para manter.

Sistemas maduros costumam usar uma combinação: REST para consultas e comandos síncronos, eventos para propagar mudanças de estado.

Documentar o “porquê”, não só o “como”

A documentação de referência descreve os endpoints. O que costuma faltar — e o que mais ajuda quem integra — é a documentação de contexto: por que a API é assim, quais são os conceitos do domínio, quais fluxos típicos ela suporta, quais erros são recuperáveis e quais não são. Um guia de “primeiros passos” e alguns cenários de uso reais economizam horas de tentativa e erro de cada nova integração.

Como a Jumps organiza esse ecossistema

A Jumps trata APIs — internas e de integração com terceiros — como parte da arquitetura, com contrato explícito em OpenAPI, testes de contrato, versionamento disciplinado e monitoramento de latência e erro por endpoint. Em contratos de sustentação e evolução, esse acompanhamento é contínuo.

Se o ecossistema de sistemas da sua empresa cresceu sem essa organização, fale com a Jumps.