como sincronizar pedidos do WooCommerce em um ERP sem ter que digitar novamente

por que os pedidos do WooCommerce ainda precisam ser digitados novamente no ERP

O financeiro ainda abre o WooCommerce, copia o número do pedido para o Comarch Optima, enova365 ou Subiekt GT, e depois digita novamente o NIP, o endereço de entrega e cada item. Essa rotina se quebra no momento em que um cliente altera o método de envio após o pagamento, um reembolso parcial ocorre, ou um SKU de pacote na loja não existe como cartão no ERP. A ponte de planilhas que funcionava com cinquenta pedidos por mês entra em colapso com alguns centenas: duas pessoas editam o mesmo CSV, as alíquotas de IVA divergem, e o estoque é separado com base em um status que a contabilidade nunca registrou. O custo maior não é o tempo de digitação. São faturas contestadas, estoque que o ERP acredita estar disponível enquanto a loja já o vendeu, e fechamentos de fim de mês que aguardam que um humano reconcilie as taxas do gateway de pagamento com a numeração de documentos. Agências que conectam lojas via NDA veem o mesmo padrão repetidamente: a loja é a frente comercial, o ERP é o livro contábil legal, e nada confiável fica entre eles, exceto o conhecimento tribal sobre qual campo personalizado significa qual depósito e qual método de pagamento corresponde a qual caixa registradora. Sem um contrato de automação, você também carece de idempotência. Atualizar a página de agradecimento ou uma nova tentativa de webhook cria um segundo documento no ERP para o mesmo ID do WooCommerce. A equipe então anula documentos manualmente, o que gera ruído de auditoria e quebra regras de numeração sequencial que alguns contadores tratam como sagradas. Lojas B2B multilíngues pioram isso: a empresa de cobrança no pedido é um grupo de IVA, o endereço de entrega é uma filial, e o ERP espera ambos como contratantes vinculados antes que um pedido de venda possa ser registrado. Pedidos de marketplace encaminhados para o WooCommerce adicionam mais um ID externo que deve permanecer correlacionado para que devoluções encontrem o documento fiscal correto. Casos-limite de moeda e impostos se acumulam. Um checkout em EUR contra uma empresa em PLN no Optima precisa de uma fonte de taxa explícita e data de lançamento. IVA reduzido em livros ou alimentos em um local não deve retornar silenciosamente para a taxa padrão porque a string da classe de imposto no WooCommerce foi renomeada durante uma limpeza de tema. Frete como um serviço tributável separado versus frete incluído no total da linha muda como o enova espera o esquema do documento. Cartões-presente, crédito da loja e recargas de carteira muitas vezes não devem nunca criar movimentos de estoque, ainda assim eles precisam de um documento financeiro ou desaparecem dos relatórios de receita. Uma correção durável trata o pedido pago do WooCommerce como um evento, mapeia SKUs e classes de impostos explicitamente, escreve um documento ERP por ID de pedido da loja e reflete as alterações de status de volta para que o suporte nunca prometa um envio que o razão contábil não tenha aceitado. Essa é a lacuna que este caso de uso fecha: não um painel sofisticado, mas uma transição confiável do carrinho para o documento contábil com responsabilidade clara quando o mapeamento falha e um caminho de reconciliação quando os webhooks foram perdidos durante a noite. Os manuais do operador devem nomear a pessoa que possui os mapas de impostos de SKU, a pessoa que libera pedidos com erros e o caminho de escalonamento quando um período fiscal é encerrado no ERP. Simulações de pico da temporada que reproduzem os pedidos pagos de ontem em uma empresa sandbox no Optima ou enova detectam desvios de mapeamento antes que atinjam os números de documentos em produção. Mantenha uma matriz escrita de métodos de pagamento para os caixas para que um novo gateway não faça lançamentos silenciosamente na caixa errada.

quando um pedido pago do WooCommerce deve criar um documento ERP

Dispare no WooCommerce em `order.paid` ou `payment_complete`, e novamente em `order.updated` quando o endereço de envio, os itens da linha ou o status mudarem após a primeira gravação bem-sucedida no ERP. Também agende uma reconciliação de quinze minutos que liste pedidos pagos que estão sem um ID de documento ERP na meta do pedido, cobrindo falhas de webhook e pedidos criados pelo administrador. Não dispare em `pending` ou `on-hold`, a menos que sua política registre reservas antes da captura; a maioria dos comerciantes poloneses e da região DACH espera pelo pagamento capturado para que Optima ou enova não criem recebíveis que nunca são liquidados. As renovações de assinatura devem usar o ID do pedido de renovação como chave de correlação, não apenas o ID da assinatura principal.

etapas para mapear itens de linha do WooCommerce em documentos de vendas do ERP

1. Validar o pedido: campos de faturamento obrigatórios, formato de NIP ou VAT para B2B, moeda permitida pela empresa do ERP e cada SKU de linha presente na tabela de mapeamento. Rejeitar com um erro estruturado se um cartão-presente ou linha virtual não tiver artigo ERP e sua política proibir saltos silenciosos. Registrar a impressão digital da validação para que tentativas idênticas sejam encurtadas.
2. Faça o upsert do contratante no ERP. Faça a correspondência primeiro pelo NIP, depois pelo e-mail, e então crie com o endereço de cobrança. Anexe o endereço de entrega como um endereço secundário quando os modelos Subiekt ou Optima segmentarem filiais separadamente do comprador legal. Preserve o ID do cliente do WooCommerce como uma chave externa para deduplicação posterior.
3. Construa o documento de vendas: mapeie os itens da linha, taxas de imposto, frete como linha de serviço ou campo de frete, cupons como descontos com o mesmo tratamento fiscal que a loja utilizou, e método de pagamento para o caixa do ERP ou código da conta bancária. Inclua taxas do marketplace como linhas de custo apenas quando a área financeira solicitar no mesmo documento.
4. Publique ou salve o documento de acordo com as regras da empresa, armazene o número do documento ERP e o ID interno nos metadados do pedido do WooCommerce e marque um estado de sincronização como `posted`, `draft` ou `needs_mapping` para que o suporte possa vê-lo sem abrir o ERP. Emita um evento interno para ouvintes do armazém ou WMS.
5. Em reembolsos ou cancelamentos posteriores, crie a nota de crédito correspondente ou documento de cancelamento vinculado ao ID original do ERP. Nunca invente um novo documento de venda para um evento de reembolso. Retorne o status do documento ERP para um status de pedido personalizado ou anote quando a postagem no armazém for concluída, incluindo atendimentos parciais quando o ERP os suportar.

como webhooks n8n e APIs de ERP transferem o payload do pedido

Prefira webhooks do WooCommerce para n8n para transferência quase em tempo real, com Action Scheduler ou WP-Cron como uma rede de segurança quando o endpoint do webhook estiver indisponível. O n8n mantém as tabelas de mapeamento, tentativas e fila de mensagens não entregues; PHP personalizado direto é aceitável para uma única empresa Optima com SKUs estáveis, mas se torna inadequado quando você adiciona enova para uma segunda entidade legal. O formato do payload é JSON de pedido da loja normalizado para um DTO interno: comprador, itens, impostos, pagamentos e IDs de correlação. O conector ERP então se comunica com a API Optima, web services da enova, ou API ou procedimento SQL de um parceiro Subiekt - escolha um conector por código de empresa e nunca compartilhe tokens entre empresas. Segredos vivem fora do banco de dados do WordPress, no cofre do host de automação. Callbacks de status do ERP, quando disponíveis, atualizam apenas o meta do pedido; eles não inventam novos pedidos da loja. O Google Sheets é aceitável como uma visão do operador de falhas, não como o sistema de registro. Para alto volume, processe em lote a varredura de reconciliação, mas mantenha o caminho do pedido pago um documento por vez para preservar as chaves de idempotência. Mantenha evidência de tratamento alinhada com orientações da CNPD quando dados pessoais saem do WordPress.

o que fazer quando o ERP rejeita uma sincronização de pedido do WooCommerce

Classifique falhas: validação (NIP incorreto, SKU ausente), transporte (tempo esgotado, 429) e rejeições comerciais (contratado bloqueado, período fechado). Erros de validação abrem um ticket no Slack ou e-mail com o link do pedido e nunca tentam nova execução automática até que o mapeamento seja corrigido. Erros de transporte tentam novamente com recuo exponencial e jitter até um limite máximo, e depois vão para dead-letter. Rejeições comerciais congelam o pedido em `needs_erp_review` e notificam a área financeira; não continue tentando um período fiscal fechado. Sempre use o ID do pedido do WooCommerce como chave ao gravar para que as tentativas sejam idempotentes. Registre hashes de requisição e resposta sem armazenar todos os dados do cartão ou PESEL cru, se ele aparecer em campos personalizados. Se o ERP aceitou o documento, mas a loja não conseguiu salvar os metadados, um trabalho de reconciliação deve detectar o órfão procurando o ID externo no ERP em vez de postar novamente. Exiba um resumo semanal da idade das mensagens não entregues para que filas silenciosas não apodreçam por um mês.

quando a entrada manual no ERP ainda é mais barata do que a sincronização de pedidos

Com cerca de oitenta pedidos pagos por mês com uma única lista de SKU que nunca muda, um funcionário treinado no Optima ainda pode ser mais barato do que construir e supervisionar conectores. Também pule se o projeto de ERP estiver em meio à migração e os esquemas de documentos mudarem semanalmente - você automatizará o caos. O dropshipping puro, onde o fornecedor fatura o cliente diretamente, geralmente precisa de um fluxo de documentos diferente de um pedido de venda clássico no Subiekt, então não force esse padrão nesse modelo.

KPIs que mostram que a sincronização do WooCommerce com o ERP está saudável

• Minutos medianos desde pagamento_concluído até o ID do documento ERP armazenado no pedido
• Participação de pedidos pagos com mais de uma hora sem um ID de documento ERP
• Contagem de documentos ERP duplicados rastreados para o mesmo ID de pedido WooCommerce por mês
• Participação das tentativas de sincronização que terminam em needs_mapping versus posted