Ficha de produto aberta mostra o registo correspondente no ERP, com SKU e stock alinhados.

Integração WooCommerce com ERP: 4 decisões antes de desenvolver

WordPress

Uma integração WooCommerce com ERP começa por decidir quem controla cada dado, quando o envia e como confirmar que o destino o processou.

Decida quem controla os dados na integração WooCommerce com ERP

Escolha um sistema responsável por cada conjunto de dados e registe a decisão antes de pedir uma solução. A matriz usa um exemplo hipotético: confirme se corresponde ao processo da loja e às capacidades do ERP.

Integração WooCommerce com ERP representada por uma ficha de produto ligada ao registo do ERP.

Matriz de responsabilidades

DadosResponsável a definirExemplo hipotético a validar
Catálogo e variantesERP ou WooCommerce: ____ERP mantém nome, SKU e variantes.
StockERP ou WooCommerce: ____ERP envia a quantidade disponível para a loja.
PreçosERP ou WooCommerce: ____ERP envia o preço de venda para a loja.
EncomendasERP ou WooCommerce: ____WooCommerce cria a encomenda; ERP recebe-a para processamento.

Para a sincronização de stock, distinga quantidade física, reservada e disponível. Num exemplo hipotético, 12 unidades físicas menos 3 reservadas deixam 9 para venda, antes de outras regras acordadas. Defina quem desconta a reserva e quando a liberta, para não descontar duas vezes a mesma encomenda. Um SKU identifica comercialmente um artigo ou variante; não é o ID local do recurso WooCommerce.

Defina quando e como os sistemas comunicam

Decida a direção e o momento de cada troca. Uma notificação webhook avisa que ocorreu um evento; uma consulta à API, interface que permite a comunicação entre sistemas, pode obter os dados necessários.

Percurso de uma encomenda entre sistemas, com notificação, consulta e confirmação distintas.

Definir o percurso dos dados

  1. Escolher a direção
    Registe o sistema de origem e o de destino para cada tipo de dado.
  2. Definir o momento
    Decida se a troca ocorre após um evento, por consulta periódica ou de outra forma suportada.
  3. Confirmar o processamento
    Defina como verificar no sistema de destino que a alteração foi realmente aplicada.

Em webhooks WooCommerce e ERP, uma resposta HTTP de entrega não prova que o ERP atualizou o registo de negócio. Defina uma confirmação própria do processamento: por exemplo, guardar o identificador devolvido pelo ERP e consultar o registo criado. A documentação oficial de webhooks WooCommerce explica a entrega e os respetivos registos; isso não substitui a confirmação de negócio no destino.

Prepare o mapa de campos e as regras de falha

Construa um mapa de campos com origem, destino, formato e identificador de cada registo. O modelo seguinte é inteiramente hipotético: os nomes de campos do ERP são ilustrativos, não uma promessa de compatibilidade. Substitua-os pelos campos documentados do sistema contratado.

Campos e identificadores de dois sistemas ligados, com uma correspondência em falta assinalada.
OrigemDestinoFormato e regraIdentificador e exemplo hipotético
ERP: codigo_artigoWooCommerce: sku da varianteTexto; preservar zeros iniciais e validar unicidade.SKU CAM-AZ-M ligado ao produto 410 e à variante 412.
ERP: disponivel_vendaWooCommerce: stock_quantityInteiro em unidades; gestão de stock ativa no nível correto.Variante 412: 9 unidades; não tratar como novo movimento de saída.
ERP: preco_baseWooCommerce: regular_priceString decimal; confirmar moeda e base de IVA.SKU CAM-AZ-M: “29.90”; não enviar “29,90 €” à API.
WooCommerce: id da encomendaERP: referencia_externaIdentidade da loja combinada com ID inteiro; guardar o ID devolvido pelo ERP.loja-teste:850 → registo ERP TESTE-27.
WooCommerce: line_itemsERP: linhas_pedidoValidar variante, quantidade e valores de cada linha.Encomenda 850, variante 412, quantidade 2; rejeitar SKU desconhecido.
Mapa de integração WooCommerce com ERP: exemplo hipotético de correspondências a validar antes do desenvolvimento.

Na REST API WooCommerce wc/v3, produtos e variantes têm id e sku distintos; as variantes pertencem a um produto. Para escrever o preço normal, use o campo documentado regular_price, não price, que é de leitura. A encomenda também tem number e order_key: não os confunda com o ID interno nem exponha a chave em registos de diagnóstico. Esta documentação não é a API legacy.

Acorde unidades, arredondamentos, moeda e se os preços incluem IVA. Uma caixa não equivale necessariamente a uma unidade. Compare totais de linhas, descontos e portes com os valores de origem; uma diferença não deve ser corrigida silenciosamente. A validação fiscal do processo cabe aos responsáveis competentes, não ao conector.

Mapa de campos: resolver diferenças antes do desenvolvimento

Uma variante não tem correspondência

Defina se fica por sincronizar e quem recebe o alerta; não associe produtos apenas por nomes semelhantes.

O mesmo pedido chega duas vezes

Use uma referência externa estável por loja e encomenda, persistida com o identificador do ERP. Ao repetir após uma falha, consulte essa correspondência antes de criar outro registo. Se a resposta se perdeu mas o ERP já criou o pedido, a repetição deve recuperar o existente, não duplicá-lo.

O sistema de destino está indisponível

Defina tentativas posteriores limitadas, registo do erro e intervenção responsável quando a falha persistir. Conserve os pedidos pendentes e o motivo da falha. Depois da recuperação, compare os registos de origem e destino; não reenvie tudo indiscriminadamente nem substitua alterações mais recentes por eventos antigos.

Use HTTPS e uma conta técnica com as permissões mínimas. As chaves REST API WooCommerce respeitam o utilizador associado e o acesso de leitura, escrita ou ambos definido na criação. Guarde segredos fora de URLs e registos, valide a autenticidade dos webhooks e documente a revogação das credenciais.

Defina testes de integração e critérios de aceitação

Execute os testes de integração num ambiente de staging isolado, isto é, uma cópia de teste separada da loja em produção, e combine previamente o resultado esperado de cada caso. Use dados fictícios e confirme as alterações no destino, não apenas o envio.

Pessoa verifica resultados esperados numa loja de teste isolada com dados fictícios.

Testes de integração com resultados esperados

Caso de teste hipotéticoEntrada e resultado esperadoProva a guardar
Stock por varianteNo ERP de teste, registar 12 unidades físicas e 3 reservadas para CAM-AZ-M. Esperar 9 unidades disponíveis na variante 412, sem alterar o stock de outra variante do mesmo produto.Capturas ou respostas dos dois sistemas, com SKU, ID da variante e quantidade final.
Encomenda e repetiçãoEnviar a encomenda fictícia 850 com duas unidades de CAM-AZ-M. Repetir exatamente a mesma referência externa. Esperar um único pedido no ERP, com as duas unidades e ligação à encomenda original.Referência loja-teste:850, ID do registo ERP e contagem de pedidos encontrados por essa referência.
Resposta perdidaPermitir a criação no ERP de teste e simular a perda da resposta. Na nova tentativa, procurar a referência externa antes de criar. Esperar a recuperação do mesmo registo, sem nova reserva ou duplicação.Histórico das tentativas e confirmação de que só existe um registo e uma reserva.
Falha e recuperaçãoSuspender o destino de testes e enviar uma alteração. Esperar pedido pendente e alerta ao responsável. Repor o destino e executar a recuperação prevista, sem substituir informação mais recente por um evento antigo.Erro inicial, estado pendente, responsável notificado e estado final confirmado no destino.
Correspondência ausenteEnviar uma linha com SKU inexistente no mapa. Esperar bloqueio dessa operação e alerta identificável, nunca associação por semelhança de nome nem criação silenciosa de um artigo errado.SKU rejeitado, motivo da rejeição e ausência de registo incorreto no ERP.
Preço e arredondamentoUsar um artigo de teste com regular_price “29.90” e quantidade 2, na moeda e base de IVA acordadas. Comparar linhas, descontos, portes e total; perante diferença, esperar revisão e não correção silenciosa.Valores de origem e destino, regra de arredondamento aplicada e decisão do responsável.

Ligue o staging apenas ao ambiente de testes do ERP e a pagamentos de teste. Bloqueie cobranças, faturas e expedições reais, emails para clientes e webhooks para destinos de produção. Uma cópia da loja pode trazer credenciais ativas: confirme o isolamento antes do primeiro teste. Para validar a recuperação sem afetar a loja, consulte Restaurar backup WordPress: verificações num teste seguro.

Antes de colocar a integração em produção, teste também cancelamento, devolução parcial e alteração de estado fora de ordem. Defina se cada caso liberta reservas, repõe stock ou apenas pede revisão humana. Um cancelamento não deve emitir automaticamente um documento fiscal nem uma devolução repor mercadoria que ainda não regressou ao armazém.

Registe para cada teste a entrada, o resultado esperado, o observado e o responsável pela aprovação. A aceitação exige correspondência dos identificadores e valores no destino, ausência de duplicados após repetição e recuperação demonstrada de uma falha. Estes são critérios propostos, não resultados de testes realizados pela UniversoWeb.

Na passagem a produção, publique apenas o conector e a configuração aprovada: não sobreponha a base de dados de staging às encomendas atuais. Combine uma janela de observação, responsável por alertas e forma de suspender a ligação sem perder pedidos pendentes. Comece por preencher a matriz e o mapa de campos com a equipa que conhece a loja e o ERP.

Após a entrada em produção, a sincronização de stock precisa de acompanhamento: atribua a alguém a revisão dos pedidos pendentes e das diferenças detetadas entre sistemas. Registe a última confirmação por referência, não apenas a hora do último envio. Uma fila vazia sem confirmação no destino não demonstra que os dados estão corretos.