Duas empresas podem pedir uma «integração do WooCommerce com o ERP» e precisar de soluções muito diferentes. Uma quer apenas enviar encomendas; outra precisa de sincronizar produtos, preços, stock, clientes, faturação e expedições.
A primeira decisão não é escolher um plugin ou perguntar se existe uma API. É perceber que processo se pretende automatizar, que dados devem circular e o que acontece quando os sistemas não estão de acordo ou deixam de comunicar.
Começar pelo processo, não pela tecnologia
Desenhe o percurso de uma encomenda, desde a compra até à faturação e à entrega. Uma empresa pode precisar do fluxo WooCommerce → ERP → faturação, enquanto outra gere os produtos no ERP, recebe encomendas na loja e comunica diretamente com a transportadora. O programa de faturação pode, inclusivamente, fazer parte do próprio ERP.
Para cada ligação, identifique quem envia, quem recebe, o evento que inicia a operação e o resultado esperado. Só depois faz sentido analisar a tecnologia disponível.
Uma API permite trocar informação entre sistemas, mas a sua existência não garante que a integração pretendida seja possível. Pode, por exemplo, permitir consultar o stock total e não disponibilizar quantidades por armazém, ou autorizar a leitura de encomendas sem permitir as operações necessárias para as atualizar. Importa confirmar os dados, as operações, os limites e as condições reais da API.
Definir os dados e o sistema responsável
«Sincronizar tudo» raramente é um requisito útil. É preferível identificar os dados necessários e determinar qual é a fonte principal de cada informação, idealmente ao nível do campo. Um sistema pode controlar as referências dos produtos, enquanto outro gere as descrições comerciais.
| Informação | Fonte principal possível | Regra a definir |
|---|---|---|
| Produtos: SKU, categorias e atributos | ERP ou sistema de gestão de informação de produtos (PIM) | Quem cria e altera cada referência, incluindo variações. |
| Descrições, imagens e SEO | WooCommerce | Que campos podem ser editados sem serem substituídos na sincronização. |
| Preços base, promoções e tabelas B2B | ERP ou WooCommerce | Que preço se aplica a cada cliente e quando é atualizado. |
| Stock | ERP | Quantidade disponível para venda, reservas e armazéns considerados. |
| Clientes e encomendas | WooCommerce na origem da compra | Que dados seguem para o ERP e como são identificados os registos existentes. |
| Faturas e notas de crédito | Software de faturação ou ERP | Quem emite os documentos e como os associa à encomenda. |
| Expedição | Sistema logístico | Quem gera etiquetas, atribui o número de seguimento e atualiza o envio. |
Esta distribuição é apenas ilustrativa. A regra essencial é saber qual o valor que prevalece quando os sistemas apresentam informação diferente. Permitir que ambos alterem livremente o mesmo campo pode originar conflitos e atualizações sucessivas.
Identificadores: como reconhecer o mesmo registo?
Um nome de produto não é uma ligação fiável entre sistemas: pode mudar ou existir em duplicado. Use referências estáveis, como SKU ou um identificador externo, e mantenha uma correspondência inequívoca entre registos. Nos produtos com variações, essa correspondência também tem de distinguir cada variação.
Nas encomendas, convém guardar no ERP o identificador de origem do WooCommerce. Para clientes, o email ou o NIF podem ser dados úteis, mas nem sempre são identificadores únicos e suficientes. É necessário definir quando criar um novo cliente, atualizar um existente ou pedir verificação.
Stock: não confundir quantidade física com disponibilidade
Se o ERP é responsável pelo stock, a loja precisa de saber que quantidade pode efetivamente vender. Isso pode exigir considerar reservas, encomendas pendentes, diferentes armazéns, vendas noutros canais e a possibilidade de aceitar encomendas sem stock.
Imagine que o ERP indica cinco unidades e o WooCommerce vende uma. A loja pode reduzir a quantidade local antes de o ERP receber a encomenda. Se uma sincronização posterior voltar a enviar o valor antigo de cinco unidades, poderá repor indevidamente stock já vendido. É preciso definir como são reconciliadas as vendas e as atualizações, incluindo cancelamentos e devoluções.
O atraso tolerável depende do produto e do volume de vendas. Num catálogo pouco movimentado, alguns minutos podem ser aceitáveis; em produtos com grande procura ou stock reduzido, o risco pode justificar uma estratégia diferente.
Quando e como deve acontecer a sincronização?
Nem todos os dados precisam de circular em tempo real. As encomendas podem exigir comunicação rápida, enquanto algumas descrições ou alterações de catálogo admitem uma atualização periódica. Para cada fluxo, defina o atraso máximo aceitável e se a comunicação ocorre num único sentido ou nos dois.
O meio técnico deve ser escolhido em função dessa necessidade:
| Mecanismo | Utilização habitual |
|---|---|
| REST API | Consultar, criar ou atualizar registos através de operações disponibilizadas pelo sistema. |
| Webhook | Comunicar a ocorrência de um evento, como a criação ou alteração de uma encomenda; pode incluir dados suficientes ou exigir consulta adicional à API. |
| Ficheiros CSV ou XML | Trocar informação periodicamente, quando não existe necessidade de atualização imediata. |
| Serviço intermédio | Transformar dados, coordenar vários sistemas e, quando necessário, gerir filas de processamento. |
No WooCommerce, a REST API permite trabalhar com produtos, encomendas e outros recursos; os webhooks permitem comunicar eventos aos sistemas externos. São mecanismos complementares, não alternativas obrigatoriamente exclusivas.
Há ainda uma decisão operacional decisiva: se o ERP ficar indisponível, a loja deve continuar a aceitar encomendas? Em muitos processos, faz sentido registar a compra e enviar os dados posteriormente. Noutros, uma validação externa é indispensável antes de confirmar a operação. Esta escolha tem de ser feita pela empresa e refletida na integração, não deixada ao acaso de uma falha técnica.
Mapear campos, permissões e dados pessoais
Os nomes e os conceitos usados por dois sistemas podem ser diferentes. O mapeamento deve documentar o campo de origem, o destino, a direção da sincronização e as regras de transformação ou validação.
A tabela seguinte usa campos da REST API v3 do WooCommerce e nomes meramente ilustrativos do lado do ERP:
| WooCommerce | ERP (exemplo) | Regra |
|---|---|---|
sku (produto) | item_code | Corresponder à referência ou variante correta. |
stock_quantity (produto/variação) | available_stock | Usar apenas quando a gestão de stock e a disponibilidade estão corretamente definidas. |
id (encomenda) | external_order_id | Guardar a origem para reconhecer operações repetidas. |
billing.company | customer_company | Nome da empresa, quando aplicável. |
billing.email | customer_email | Contacto de faturação; não presumir que identifica sozinho o cliente. |
Em billing.company e billing.email, a notação representa campos dentro do objeto billing da encomenda. As designações do ERP dependem da API concreta e devem ser confirmadas na documentação do fornecedor. O mesmo cuidado aplica-se aos estados: «em processamento» no WooCommerce não equivale automaticamente a «enviado» na plataforma logística ou a «faturado» no ERP.
Quanto à segurança, as chaves da REST API do WooCommerce estão associadas a um utilizador WordPress e permitem configurar acesso de leitura, escrita ou ambos, sujeito às permissões desse utilizador. Devem ser usados apenas os acessos necessários, através de ligações seguras e sem expor credenciais no website público.
Os webhooks suportam uma assinatura HMAC-SHA256 que o sistema recetor deve verificar. Os dados pessoais transmitidos — como nome, NIF, email, telefone e morada — também devem limitar-se ao que o processo exige, com proteção adequada nos sistemas e nos registos de diagnóstico.
Prever falhas, duplicados e recuperação
Uma integração tem de funcionar também quando algo corre mal. Se o WooCommerce envia uma encomenda ao ERP e o pedido termina por falta de resposta, não é seguro concluir que a operação falhou: o ERP pode ter recebido os dados e a confirmação ter-se perdido.
Por isso, cada operação deve poder ser reconhecida quando é repetida. Por exemplo, uma encomenda com referência externa WC-12345 não deve originar uma segunda encomenda ou uma segunda fatura só porque houve uma nova tentativa de envio. Este comportamento é conhecido como idempotência.
Defina previamente um número limitado de novas tentativas, os intervalos entre elas, a possibilidade de colocar operações em fila e o momento de pedir intervenção humana. Uma falha não deve desaparecer silenciosamente nem gerar tentativas sem fim.
Os registos da integração devem permitir saber qual foi a operação, quando ocorreu, que sistema respondeu e qual foi o erro, sem conservar dados sensíveis desnecessários. O WooCommerce disponibiliza registos de entregas de webhooks e pode desativá-los após falhas consecutivas. É igualmente necessário acompanhar o sistema recetor, criar alertas relevantes e verificar periodicamente se existem encomendas por sincronizar.
Faturação e logística exigem regras próprias
Faturação: quando e que documento emitir?
Criar uma encomenda, confirmar um pagamento, entregar um produto e emitir uma fatura são acontecimentos distintos. A integração deve identificar o evento adequado, os dados fiscais necessários, o tratamento de portes e descontos, e o que fazer perante cancelamentos, devoluções e notas de crédito.
Em Portugal, o momento de emissão de uma fatura está sujeito a regras fiscais, incluindo situações em que existe pagamento antecipado. Não deve ser decidido apenas pelo estado de uma encomenda no WooCommerce. O NIF, quando necessário, também exige recolha e mapeamento específicos, pois não é um campo de faturação padrão na REST API do WooCommerce. O procedimento deve ser validado com o responsável contabilístico e o fornecedor do software de faturação, antes da implementação.
Logística: quando preparar e acompanhar a expedição?
A criação de uma encomenda não significa que a mercadoria deva ser imediatamente expedida. O envio para a transportadora pode depender da confirmação do pagamento, da disponibilidade ou de uma aprovação interna.
Depois, é necessário definir os dados enviados — morada, artigos, quantidades, peso e serviço de entrega — e os resultados recebidos, como etiqueta, número de seguimento e estado da expedição, bem como a documentação de transporte aplicável. A apresentação de informações de seguimento no WooCommerce pode exigir uma extensão ou integração própria; não deve ser assumida como funcionalidade disponível em qualquer instalação.
Escolher a solução e testar antes do lançamento
Um plugin de integração existente pode ser a escolha mais simples, desde que suporte os dados, os sentidos de sincronização, os estados, o tratamento de erros e o volume necessário. Quando existem regras específicas ou vários sistemas a coordenar, pode justificar-se desenvolvimento próprio ou um serviço intermédio. A avaliação deve incluir suporte, manutenção, limites das APIs e compatibilidade com a instalação, nomeadamente com o armazenamento de encomendas de elevado desempenho (HPOS) do WooCommerce.
Num ambiente de testes, e preferencialmente com um ambiente de demonstração do sistema externo, importa simular pelo menos:
- Uma compra paga, outra com pagamento pendente e uma encomenda cancelada.
- Um produto ou variação inexistente, stock esgotado e vendas próximas no tempo.
- Dados fiscais ou de entrega incompletos e campos sem correspondência.
- Indisponibilidade da API, falta de resposta e receção repetida do mesmo pedido.
- Uma devolução ou reembolso e a respetiva atualização dos sistemas.
- A recuperação de operações pendentes sem criar documentos ou encomendas duplicados.
Os testes não devem emitir documentos fiscais reais por engano nem alterar dados de produção. Após o lançamento, é necessário definir quem acompanha os alertas, resolve falhas e mantém a integração quando mudam APIs, credenciais, extensões ou processos da empresa.
Checklist antes de desenvolver
Antes de escolher o conector ou iniciar a programação, confirme:
- Estão identificados os sistemas, os fluxos e o evento que inicia cada operação?
- Está definido que dados circulam, em que direção e qual é a fonte principal de cada campo?
- Existem identificadores estáveis e regras para correspondências, alterações e duplicados?
- Foram definidos o atraso aceitável, o mecanismo de ligação e os limites técnicos?
- Estão documentados os campos, estados, permissões e dados pessoais necessários?
- Sabe-se o que acontece quando um sistema falha e como se recuperam operações pendentes?
- Existem registos, alertas, responsabilidades e um processo de reconciliação?
- Estão previstos testes sem impacto na produção e manutenção após o lançamento?
Conclusão
Uma integração bem concebida não se mede apenas por conseguir enviar informação do WooCommerce para outro sistema. Mede-se também pela capacidade de manter encomendas, stock, documentos e estados coerentes, mesmo perante atrasos e falhas.
Definir primeiro os processos, as responsabilidades e as exceções permite escolher uma solução proporcional à operação e reduzir problemas durante a utilização diária.
