A integração entre loja e retaguarda quase nunca falha no dia em que é entregue. Ela falha meses depois, em um pico de volume, com um pedido que o ERP recebeu duas vezes e um estoque que ninguém consegue explicar.
Na integração Magento ERP, os problemas raramente vêm de erro de programação. Vêm de decisões de arquitetura que pareciam detalhe no início do projeto. Este guia reúne as decisões que mais pesam: quem é dono de cada dado, como a loja conversa com o ERP, o que acontece quando algo falha e como saber disso antes do cliente.
Principais pontos
- A pergunta que vem antes de qualquer linha de código é: quem é a fonte da verdade de cada dado?
- Chamada síncrona ao ERP no fluxo de compra é a decisão que mais derruba a operação em pico.
- Sem idempotência, todo reprocessamento vira risco de pedido duplicado.
- Fila sem monitoramento é a falha mais cara, porque ninguém percebe até o cliente reclamar.
- Atualizações em massa pedem cuidado com o banco de dados e com os indexadores do Magento.
- Um teste simples, que cabe em um dia no ambiente de homologação, mostra se a integração aguenta o pico.
Quem é a fonte da verdade
Essa é a primeira pergunta e a que mais gera retrabalho quando é respondida tarde. Para cada dado que existe nos dois sistemas, alguém precisa ser dono.
Estoque, preço, cadastro de produto, cadastro de cliente, status de pedido e nota fiscal podem ter origem no ERP, no Magento ou em um terceiro sistema. O que não pode é ter dois donos: nesse cenário, a última escrita vence, e a última escrita depende da ordem de sincronização, que depende da latência, que varia.
O sintoma clássico é o preço que “volta sozinho”. Alguém ajusta uma promoção no painel do Magento, o ciclo de sincronização do ERP roda, e o preço antigo retorna. Isso não é bug. É ausência de definição de propriedade, e a correção é uma decisão de negócio que precisa ser tomada, escrita e aplicada de forma consistente.
Monte uma tabela com uma linha por tipo de dado e três colunas:
- Sistema dono: quem cria e altera o dado.
- Sistema leitor: quem apenas consome.
- Frequência de sincronização: a cada evento, em intervalos curtos ou em lote diário.
Se alguma linha tiver dois donos, você encontrou uma falha futura antes que ela aconteça.
Onde entram PIM, DAM, OMS e iPaaS
Na prática, o ERP raramente é o único sistema em volta da loja. Cada sigla abaixo é um sistema com um papel diferente, e a tabela de donos precisa incluí-los:
- ERP: pedidos, estoque, finanças, logística e fiscal. Sabe tudo sobre a operação, mas costuma saber pouco sobre o conteúdo comercial do produto.
- PIM (gerenciamento de informações do produto): reúne descrições, atributos e dados técnicos e de marketing, enriquece e publica nos canais. Combina o dado do ERP com o conteúdo que o cliente lê.
- DAM (gestão de ativos digitais): guarda imagens, vídeos e documentos. O PIM costuma distribuir esses arquivos junto com os dados do produto.
- OMS (sistema de gerenciamento de pedidos): centraliza pedidos de todos os canais, escolhe de onde cada pedido sai e acompanha o atendimento. Importa quando a empresa vende em mais de um canal ou tem mais de um estoque.
- iPaaS (plataforma de integração como serviço): plataforma em nuvem que concentra as integrações em um só lugar, em vez de conexões ponto a ponto. Reduz a quantidade de conectores soltos para manter, e vale comparar o custo total, incluindo suporte e evolução, e não só a mensalidade.
Quanto mais sistemas na rota, mais importante é a regra “um dado, um dono”.
Síncrono no fluxo de compra é a armadilha mais cara
Consultar o ERP em tempo real para confirmar o estoque no momento em que o cliente clica em finalizar compra parece a decisão mais segura. Ela é a que mais derruba loja em pico.
O motivo é simples: a disponibilidade do checkout fica acoplada à disponibilidade e ao tempo de resposta de um sistema que não foi dimensionado para tráfego de internet. Em volume normal, funciona. No pico, o ERP responde mais devagar, o checkout acumula requisições em espera e a fila cresce mais rápido do que esvazia. O cliente vê um checkout lento e depois um checkout que não responde.
O padrão que recomendamos é outro:
- O Magento é a fonte de verdade operacional durante a compra, com estoque reservado localmente.
- O pedido é aceito e entra em uma fila.
- O ERP consome a fila no ritmo que consegue.
- Uma reconciliação periódica compara os dois lados e corrige divergências.
Com esse desenho, se o ERP ficar fora do ar por alguns minutos, a loja continua vendendo e a fila acumula.
Há exceções legítimas, como itens de valor muito alto ou estoque compartilhado em tempo real com loja física. Elas devem ser exceções declaradas para parte do catálogo, e não a arquitetura padrão de toda a operação.
Como o Magento trata filas
O Magento tem um framework de filas de mensagens: um módulo publica mensagens em filas e consumidores as processam. Segundo a documentação da Adobe, o RabbitMQ é o principal broker de mensagens do Adobe Commerce. Há também um adaptador baseado em MySQL, que dispensa um broker externo, mas a própria Adobe o descreve como pouco escalável e recomenda um broker externo sempre que possível. Os consumidores dependem de tarefas agendadas (cron) para receber as mensagens, então cron e fila precisam ser monitorados juntos.
Referência: documentação da Adobe sobre o framework de filas.
Idempotência: por que reprocessar é perigoso
Toda integração assíncrona vai falhar em algum momento: timeout, indisponibilidade, erro de validação. A pergunta não é se, e sim o que acontece depois.
Reprocessar é a resposta natural, e ela só é segura se cada operação for idempotente: executá-la duas vezes produz o mesmo resultado que executá-la uma vez. Para isso, cada mensagem carrega um identificador único, e o sistema receptor reconhece que já processou aquele identificador.
Sem isso, o cenário é conhecido. A rede falha depois que o ERP gravou o pedido e antes de confirmar o recebimento. Alguém reprocessa a fila, e o pedido entra duas vezes. A descoberta acontece no fechamento do mês, quando o número de pedidos não bate com o número de notas.
Idempotência é decisão de projeto. Adicionar depois exige mexer nos dois lados da integração e em dados já processados: custa pouco no desenho inicial e caro no retrofit.
Erros de projeto que aparecem antes do go-live
Além dos três pontos acima, estes problemas se repetem em integrações Magento ERP e quase sempre nascem no planejamento:
- Mapeamento de campos feito às pressas: campos que parecem equivalentes, como código de produto no Magento e SKU no ERP, podem ter regras de formação diferentes. Valide com amostras reais, incluindo variações de cor e tamanho, kits, produtos sob encomenda e itens com tributação diferenciada.
- Modelos de dados diferentes: um “pedido” no Magento pode virar vários documentos fiscais no ERP, conforme a operação e o estado do cliente. Trate essa diferença antes de implementar.
- Conflito de estoque sem regra: o que acontece quando o Magento registra uma venda no mesmo segundo em que o ERP atualiza o saldo? Defina qual versão prevalece.
- Tratamento de erro inexistente: quando a API do ERP devolve erro, o pedido não pode ficar em estado indefinido nem gerar uma confirmação de compra que o ERP nunca processou. Falha faz parte do desenho: fila de reprocessamento, alerta para o time e aviso claro ao cliente quando o pedido precisar de atenção manual.
- Homologação com dados fictícios: o ERP de produção tem regras fiscais por estado, preços por canal e condições de pagamento por tipo de cliente. Teste com uma amostra real, incluindo devoluções, cancelamentos, produtos fora de linha e clientes com CNPJ em vez de CPF.
- Contratos de API sem documentação: o ERP atualiza, o Magento recebe novos módulos e o time muda. Sem contrato versionado, toda atualização vira investigação do zero.
- Regra de negócio dentro da integração: integração transporta dados, e não toma decisão. Cálculo de desconto, prazo de entrega e escolha de depósito pertencem aos sistemas, não à camada que os conecta.
Gargalos de banco e indexadores
Quando o ERP envia grandes volumes sem controle, o problema deixa de ser só de fila e passa a ser de banco de dados.
Deadlocks
Um deadlock acontece quando duas ou mais transações disputam os mesmos recursos do banco e ficam bloqueadas entre si. O banco cancela uma delas para liberar o sistema, mas o efeito já apareceu: lentidão, erros intermitentes, carrinhos travados e pedidos não concluídos. No Magento, isso aparece com mais frequência em atualizações simultâneas de estoque, reindexações concorrentes, importações em massa de produtos e sincronização de pedidos.
Para reduzir o risco:
- divida cargas grandes em lotes menores;
- controle a concorrência de escrita, evitando vários processos alterando as mesmas tabelas ao mesmo tempo;
- mova operações pesadas para filas assíncronas;
- revise consultas e índices, porque consulta lenta aumenta o tempo de bloqueio;
- acompanhe o log do banco em busca de lock wait timeout.
Indexadores
Os indexadores do Magento pré-processam dados, como preço por grupo de clientes, regras de catálogo e estoque, para que a loja não precise calcular tudo a cada visita. Existem dois modos:
- Atualizar ao salvar (Update on Save): cada alteração dispara a reindexação na hora.
- Atualizar por agendamento (Update by Schedule): uma tarefa agendada reindexa em lote, e só quando há alterações registradas.
A Adobe recomenda o modo por agendamento para sites grandes e para sites com atualizações frequentes e muito tráfego, porque reindexar com frequência degrada o desempenho do banco. Em uma integração em que o ERP envia milhares de atualizações, esse é o modo mais seguro. O cuidado está no cron: se ele falhar ou acumular tarefas, a loja demora a refletir as mudanças. Veja a documentação da Adobe sobre configuração de indexadores.
Fila sem monitoramento é a falha silenciosa
A integração assíncrona resolve o acoplamento e cria um novo problema: a fila. Quando ela para de esvaziar, nada quebra visivelmente. A loja continua vendendo, o painel continua respondendo, e os pedidos se acumulam sem chegar à retaguarda. A descoberta costuma vir pelo pior canal: o cliente perguntando por que o pedido de três dias atrás não foi faturado.
O mínimo aceitável são quatro indicadores com alarme:
- Profundidade da fila: quantas mensagens aguardam.
- Idade da mensagem mais antiga: é o indicador mais útil e o menos usado. Uma fila com muitas mensagens que esvazia rápido é saudável, e uma fila com poucas mensagens paradas há horas é um incidente em andamento.
- Taxa de consumo: quantas mensagens saem por minuto.
- Taxa de erro por tipo de mensagem: mostra qual fluxo (pedido, estoque, preço) está com problema.
Sinais de que a integração precisa ser revista
- Picos de CPU após cada sincronização, reindexações demoradas e erros intermitentes de banco.
- Filas acumuladas e pedidos que demoram a aparecer no ERP.
- Correções manuais todos os dias e nenhum log acessível para investigar falhas.
Quando vários sinais aparecem juntos, o problema costuma ser de arquitetura, e remendos pontuais custam mais do que um redesenho planejado.
O teste que mostra se a integração aguenta o pico
Existe um exercício simples, que cabe em um dia no ambiente de homologação e vale antes de qualquer temporada de alto volume, como a descrita no checklist de Black Friday para Magento.
Derrube o ERP de propósito. Desligue a integração, mantenha a loja recebendo pedidos de teste por um período de pelo menos meia hora e depois religue.
Três perguntas se respondem sozinhas:
- A loja continuou vendendo normalmente, ou o checkout degradou?
- A fila acumulou sem perder mensagem?
- Quando o ERP voltou, a fila esvaziou sem gerar pedido duplicado?
Se as três respostas forem positivas, a integração foi desenhada para operar sob falha, que é o que um pico de tráfego produz. Se alguma for negativa, você encontrou em ambiente controlado o incidente que aconteceria em produção.
Como a Trezo pode ajudar
A Trezo trabalha só com Magento e Adobe Commerce desde 2009. Mapeamos os fluxos entre loja e ERP, revisamos arquitetura de filas, banco e indexadores, e monitoramos as lojas dos nossos clientes 24 horas por dia, 7 dias por semana. Somos Adobe Solution Partner e AWS Partner, com certificação ISO 27001. Conheça também nossa sustentação em Magento.
Se essa conversa está em aberto na sua operação, fale com nossos especialistas.
Perguntas frequentes
Para a maior parte das operações de médio e grande porte, o padrão que recomendamos é assíncrono, por fila, com o Magento como fonte de verdade operacional durante a compra e reconciliação periódica com o ERP. Integração síncrona no checkout deve ser exceção declarada.
Depende do giro do produto e da tolerância do negócio a divergência. Itens de alto giro e estoque baixo pedem sincronização em intervalos curtos, e itens de baixo giro toleram janelas maiores. O erro comum é aplicar a mesma frequência a todo o catálogo, o que gera carga desnecessária no ERP.
O conector é mais rápido quando o ERP é amplamente adotado e o conector é mantido pelo fornecedor. O desenvolvimento próprio faz sentido quando o ERP é proprietário, quando há regras de negócio específicas ou quando o conector não cobre as entidades necessárias. O critério é cobertura funcional e manutenção, e não só o custo inicial.
Comece pelos logs da integração. Se há registro de tentativa de envio, o problema está na API do ERP ou em uma regra de validação que rejeitou os dados. Se não há registro, o problema vem antes, no evento que deveria ter disparado o envio. Toda integração precisa de alerta para pedidos não confirmados pelo ERP dentro de um prazo definido.
É a propriedade de uma operação que, executada duas vezes, produz o mesmo resultado que uma execução. Ela permite reprocessar mensagens com segurança, sem duplicar pedidos.
O ERP cuida da operação (pedidos, estoque, finanças e fiscal). O PIM reúne e distribui as informações comerciais do produto. O OMS centraliza e distribui os pedidos de todos os canais. Cada um precisa de uma regra clara de quem é dono de qual dado.
Divida cargas grandes em lotes, controle a concorrência de escrita, use filas assíncronas e revise consultas e índices do banco de dados.
