Integrações do WooCommerce com ERP e APIs de grossistas

#Integrações do WooCommerce com ERP e APIs de grossistas

Se precisa de ajuda geral para construir e fazer crescer uma loja, comece pela página do programador de WooCommerce. Esta página trata de um problema mais restrito e técnico: a troca de dados entre o WooCommerce e sistemas externos.

#O que é realmente uma integração do WooCommerce

Na maioria das lojas, a verdade sobre os produtos não vive no WooCommerce. Vive no ERP, no sistema de armazém ou numa API de grossista. O WooCommerce é a frente de vendas, mas o stock, os preços e parte dos dados de produto vêm de outro lado. Uma integração é a camada que mantém esses dois mundos em concordância.

Na prática, uma integração responde a três perguntas:

• O que sincronizamos - catálogo, atributos, níveis de stock, preços, encomendas, dados de clientes.
• Em que sentido - unidirecional (o sistema de origem dita à loja) ou bidirecional (por exemplo, as encomendas voltam para o ERP).
• Com que frequência - desde consultas agendadas de poucos em poucos minutos até atualizações desencadeadas por eventos através de webhooks.

#O que pode integrar com o WooCommerce

Não tem de fazer tudo de uma vez. O primeiro passo mais comum é a sincronização de stock e preços, porque é o que se paga mais depressa em tempo de apoio recuperado e reembolsos evitados.

#Como funciona a sincronização de dados

A mecânica é semelhante em todos os casos, quer a origem seja um ERP quer uma API de grossista. Muda a origem, não o princípio.

#Mapeamento de dados

O sistema de origem descreve os produtos com a sua própria estrutura de campos. A primeira tarefa de uma integração é traduzir isso para o modelo de produtos e atributos do WooCommerce: EAN e referência como as chaves que ligam os registos, atributos técnicos para atributos e variações, media e descrições para as páginas de produto. Mantemos o mapa de campos declarativo, por isso adicionar um novo parâmetro significa alargar o mapeamento, não reescrever a lógica.

#Sincronização de stock e preços

O núcleo da maioria das integrações é a consulta agendada de duas coisas: nível de stock e preço. Os artigos indisponíveis no sistema de origem são automaticamente ocultados ou marcados como indisponíveis, o que elimina a falha mais cara que uma loja pode cometer - vender algo que não pode ser cumprido. Uma alteração de preço no sistema de origem propaga-se para a loja no ciclo seguinte.

#Lógica de margem

Os preços de um ERP ou grossista são, normalmente, o custo e não o preço de venda. Acima da camada de recolha de dados fica a lógica de margem: o sistema aplica uma margem definida sobre o preço de origem e só o resultado chega ao WooCommerce. O proprietário controla a rentabilidade com regras, não editando preços à mão.

#Uma integração real

A mesma mecânica está por trás do nosso projeto para uma loja de peças automóveis ligada diretamente à API REST de um grossista: integração do WooCommerce com API de grossista. Nesse caso, o catálogo, o stock e os preços mantêm-se atualizados sozinhos, e a margem protege a rentabilidade face a uma lista de fornecedor em constante mudança.

#Com que sistemas ERP integramos

Uma distinção importante: integramos o WooCommerce com a API destes sistemas, não implementamos o ERP em si. Este é trabalho de WordPress, PHP e troca de dados, não consultoria de ERP.

• ERP na cloud: Microsoft Dynamics 365 Business Central, SAP Business One, Oracle NetSuite, Odoo. Estes expõem APIs REST, o que mantém a ligação à loja limpa.
• Contabilidade e ERP nacionais: sistemas como PHC, PRIMAVERA ou Sage consoante o mercado, normalmente integrados através da sua API ou de uma camada de middleware.

Se o seu sistema não estiver na lista mas tiver alguma API ou exportação de dados, é geralmente possível integrá-lo.

#Como arquitetamos integrações para ERPs específicos

Cada ERP tem a sua própria API, formato de dados e armadilhas. Abaixo fica a forma como abordamos os sistemas mais comuns. São padrões de arquitetura, não um plugin comprado por uns euros.

#SAP Business One - escala e o problema do wp_postmeta

Distribuição industrial: dezenas de milhares de produtos ativos, atualizações de preços frequentes (várias vezes ao dia quando o câmbio se mexe), centenas de atributos. A estrutura EAV predefinida do WordPress guarda cada atributo em wp_postmeta, o que a essa escala inflaciona para milhões de linhas; as atualizações de preços em tempo real provocam então deadlocks no MySQL e timeouts 504 para os compradores.

• HPOS e tabelas personalizadas: deixamos de escrever atributos em wp_postmeta e usamos uma tabela MySQL plana dedicada, construída para as consultas do SAP B1.
• Elasticsearch como camada de pesquisa: o SAP atualiza os dados no Elasticsearch via API e a frente vai buscar resultados e filtros a partir daí, contornando o MySQL. Esta camada pode reduzir o TTFB de segundos para a ordem dos ~150 ms.
• Filas (RabbitMQ): as atualizações do SAP entram numa fila de mensagens e um worker em segundo plano vai buscando lotes de algumas centenas de produtos de cada vez, mantendo a loja responsiva 24/7.

#Microsoft Dynamics 365 (com BaseLinker e POS)

Um grande retalhista a vender através do WooCommerce, de marketplaces (via BaseLinker) e de lojas físicas com um POS sobre o Dynamics 365. Sem uma hierarquia rígida obtém-se ciclos de sincronização e condições de corrida (a última unidade vendida na loja física e um segundo depois num marketplace), produzindo stock negativo.

• Fonte única de verdade: impomos uma hierarquia em que o Dynamics é o mestre absoluto e o WooCommerce e o BaseLinker são escravos.
• Camada Redis: em vez de consultar constantemente a API lenta do Dynamics, executamos o Redis em memória. Uma venda na loja física dispara um webhook que atualiza o Redis, e o WooCommerce e o BaseLinker verificam a disponibilidade no Redis (resposta de poucos milissegundos) antes de finalizar um carrinho, eliminando a sobrevenda.

#Odoo (open source) - configuradores por encomenda

Os fabricantes configuram produtos no Odoo (uma lista de materiais) onde o preço de um componente depende de outras escolhas. As variações do WooCommerce não conseguem modelar isso, e transpor a lógica de produção para PHP produz código impossível de manter.

• Abordagem desacoplada / headless: o WooCommerce é o carrinho e o sistema de transações (pagamento, emails), enquanto o frontend (Astro/Vue) fala diretamente com a API do Odoo, pedindo preços e viabilidade de produção em tempo real. No “adicionar ao carrinho”, é enviado para o WooCommerce um produto personalizado com um preço calculado pelo Odoo e um PDF de especificação gerado, sem duplicar a lógica de negócio.

#Comarch Optima, InsERT Subiekt, enova365 (mercado polaco e da Europa Central e de Leste)

• Comarch Optima: o Optima expõe dados através de um WebService/API, por isso construímos middleware dedicado em PHP e usamos sincronização diferencial (delta) - um trabalho CRON pede apenas as referências alteradas na última janela, reduzindo a carga do MySQL numa ordem de grandeza face a uma importação completa. Os preços B2B são calculados em tempo real a partir do grupo de desconto do cliente, em vez de guardados como milhares de variações de preço em wp_postmeta.
• InsERT Subiekt GT / nexo: troca de dados através de EPP e API; uma reserva rígida bloqueia o stock no Subiekt durante alguns minutos no checkout para evitar a sobrevenda em picos, e um documento de correção dispara um webhook que muda a encomenda do WooCommerce para devolvida e repõe o artigo em stock.
• enova365: para produtos com muitas variantes (cores x tamanhos, cada um com o seu próprio EAN) usamos variantes planas mapeadas para JSON e carregadas de forma assíncrona por REST, em vez de gerar centenas de milhares de posts product_variation.

#JTL-Wawi (Alemanha) e Holded (Espanha)

• JTL-Wawi: omnicanal com múltiplos armazéns. O encaminhamento lógico analisa o código postal do cliente e escolhe algoritmicamente o armazém com envio mais rápido; o tratamento do One Stop Shop recalcula o IVA em tempo real por país de destino, para que a fatura no JTL tenha a taxa correta. O WooCommerce corre em paralelo com o BaseLinker para a Amazon e o eBay.
• Holded: um ERP na cloud, API-first - uma integração totalmente sem ficheiros sobre a API REST nativa com autenticação por token e webhooks. A lógica de faturação reconhece o valor do carrinho e sinaliza ao Holded para gerar o tipo de documento correto (por exemplo, uma fatura simplificada para valores pequenos), devolvendo um PDF para anexar ao email do WooCommerce.

#Arquitetura enterprise: desempenho e fiabilidade

À escala de um grande ERP passamos para além do “instalar um plugin”. Isto é engenharia exigente:

• Headless / desacoplado: o WordPress é o motor de administração (backend) e a loja renderiza em Astro ou Next.js, acedendo a uma API GraphQL ou REST e contornando o SQL lento, o que torna a loja mais rápida e mais resiliente. Mais em soluções enterprise.
• Processamento assíncrono (filas): sincronizar dezenas de milhares de produtos num simples script PHP dá timeout. Baseamo-nos em filas (RabbitMQ ou Redis) que processam pequenos blocos em segundo plano.
• Tratamento de erros e registo: se a API do ERP não responder, bloqueamos o checkout com uma mensagem em vez de aceitar encomendas para o vazio; o registo completo de erros permite um diagnóstico rápido.

#Problemas técnicos que resolvemos

• Limitação de pedidos da API (429): os sistemas na cloud limitam os pedidos. Implementamos exponential backoff (perante um 429 o script espera e volta a tentar) mais chunking, empacotando dados em pedidos JSON bulk-update em vez de milhares de chamadas individuais.
• Incompatibilidades de tipo de dados (arredondamento): um ERP pode guardar preços com quatro casas decimais enquanto o WooCommerce espera duas. No middleware aplicamos type casting estrito e reconciliamos o arredondamento por linha de fatura, evitando erros ao cêntimo que se acumulam ao longo de centenas de encomendas.
• Imagens, largura de banda e o limite de inodes: importar imagens físicas para a biblioteca de media do WordPress (gerando vários thumbnails cada uma) esgota o limite de ficheiros do servidor. Em vez disso, servimos as imagens a partir de armazenamento externo (Amazon S3 ou Cloudflare Image Resizing) através de URLs mapeados a partir do ERP, poupando espaço e acelerando a própria sincronização.

#Quando vale a pena considerar uma integração

• Atualiza o stock e os preços à mão ou por importação de ficheiros, e isso não é escalável.
• Recebe encomendas de produtos que o fornecedor não tem realmente em stock.
• Os preços da loja afastam-se da lista de preços do grossista ou do ERP.
• As encomendas têm de ser reintroduzidas à mão no sistema de contabilidade ou de armazém.