WooCommerce — Integração com E-commerce¶

Aplicativo externo IntegraWooCommerce.exe | Sincronização automática em intervalo configurável

O que é¶

A Integração WooCommerce é um aplicativo standalone (separado do Master Key) que sincroniza dados entre o Master Key e uma loja na plataforma de e-commerce WooCommerce (WordPress). A sincronização ocorre em ciclos automáticos com execução paralela das etapas independentes.

O fluxo é bidirecional: - WooCommerce → Master Key: clientes e pedidos - Master Key → WooCommerce: categorias, produtos, variações de grade e imagens

Pré-requisitos¶

URL base da loja WooCommerce e credenciais de API REST do WooCommerce (Consumer Key + Consumer Secret), obtidas em WooCommerce → Configurações → Avançado → REST API
Banco de dados do Master Key acessível pelo computador onde o aplicativo roda

Configuração¶

Acesse o menu Opções → Configurações no aplicativo. As configurações são salvas em arquivo INI na mesma pasta do executável.

API¶

Campo	O que é
URL	URL base da loja (ex.: `https://sualoja.com.br`). O aplicativo acrescenta automaticamente `/wp-json/wc/v3/`
Consumer Key	Chave de consumidor gerada na API REST do WooCommerce
Consumer Secret	Segredo de consumidor gerado na API REST do WooCommerce

A autenticação é feita via HTTP Basic Auth com Consumer Key e Consumer Secret. Sem essas credenciais o ciclo falha em todas as chamadas à API.

Estoque¶

Campo	O que é
Filiais de Estoque	Filiais cujos saldos somam para calcular o estoque enviado

Filiais de estoque são obrigatórias para a etapa de Produtos. O ciclo aborta com erro se não estiverem configuradas.

Pedidos¶

Campo	O que é
Vendedor	Código do vendedor padrão atribuído a cada pedido importado
Transportador	Código do transportador padrão atribuído aos pedidos
Finalizar Pedidos	Quando marcado, envia de volta ao WooCommerce o status de conclusão dos pedidos faturados no Master Key

Clientes¶

Campo	O que é
Praça	Praça padrão atribuída ao cliente
Atividade	Atividade padrão atribuída ao cliente

O Vendedor de clientes é compartilhado com a configuração de Pedidos. Praça e Atividade são obrigatórias.

Produtos¶

Campo	O que é
Tabela de Preço	Tabela usada para o preço de venda (`regular_price`). Opções: `Preço de Venda`, `Preço de Venda 2` ou tabela cadastrada

Campos de Inserção / Atualização¶

A tela apresenta duas abas de campos configuráveis por grupo (Categorias, Produtos, Grades, Imagens): - Inserção: campos enviados quando o registro ainda não existe no WooCommerce - Atualização: campos enviados ao atualizar um registro já existente

A etapa de Imagens só é executada se o campo Imagem estiver marcado na aba de Atualização.

Fluxo de Sincronização¶

A cada ciclo, o aplicativo executa as etapas com a seguinte ordem de dependências:

Configurações ──► Clientes ──────────────────────────────────┐
                                                              ▼
Configurações ──► FinalizarPedidos ──► Pedidos ──► Produtos ──► Imagens
                                                       ▲
Categorias ────────────────────────────────────────────┘

Configurações e Categorias iniciam em paralelo. Clientes e Pedidos dependem de Configurações. Produtos aguarda Configurações, Categorias e o término do ciclo de Pedidos. Imagens aguarda Produtos.

1. Configurações¶

Carrega parâmetros do sistema e valida a conexão com a API antes de liberar as demais etapas.

2. Finalizar Pedidos¶

Se Finalizar Pedidos estiver marcado, verifica pedidos faturados no Master Key e atualiza o status correspondente no WooCommerce para completed.

3. Clientes (WooCommerce → Master Key)¶

Os clientes são importados sob demanda: a etapa de Pedidos notifica esta etapa sempre que encontra um cliente novo. A etapa de Clientes processa cada notificação buscando os dados completos via GET customers/{id}.

Para cada cliente: - Busca no Master Key por ID externo, CPF, CNPJ, RG ou e-mail para evitar duplicatas - Se encontrado, atualiza o cadastro existente - Se não encontrado, cria um novo cliente com tipo conforme persontype (F=C, J=F, demais=A) - Define consumidor como N se tiver inscrição estadual válida (não "ISENTO") e a filial for do ramo indústria/atacado - Importa o endereço de cobrança (billing) e o endereço de entrega (shipping) - Resolve cidade/UF pelo estado informado; se não encontrar, consulta o serviço de CEP. Se ainda assim não resolver, registra UF=!! e Cidade=Cidade Inexistente!

Campos importados:

Campo WooCommerce	Campo Master Key	Descrição
`first_name` + `last_name`	`CL_NOME`	Nome completo
`email`	`CL_EMAIL`	E-mail
`billing.cpf`	`CL_CPF`	CPF
`billing.cnpj`	`CL_CGC`	CNPJ
`billing.rg`	`CL_CI`	RG
`billing.ie`	`CL_INSCRICAO`	Inscrição Estadual
`billing.phone`	`CL_FONE`	Telefone
`billing.cellphone`	`CL_CELULAR`	Celular
`billing.address_1`	`CL_ENDERECO`	Logradouro
`billing.number`	`CL_NRO`	Número
`billing.address_2`	`CL_COMPL`	Complemento
`billing.neighborhood`	`CL_BAIRRO`	Bairro
`billing.postcode`	`CL_CEP`	CEP
`billing.state` + `billing.city`	`CL_UF` + `CL_CIDADE`	Estado e cidade
`billing.sex`	`CL_SEXO`	Sexo
`billing.birthdate`	`CL_DTNASC`	Data de nascimento

4. Pedidos (WooCommerce → Master Key)¶

Importa pedidos modificados desde a última sincronização, 20 por página. Executa após Configurações e em paralelo com a etapa de Finalizar Pedidos, bloqueando Produtos até concluir.

Para cada pedido: - Notifica a etapa de Clientes para importar o cliente do pedido - Cria ou atualiza o pedido no Master Key - Pedido existente não é atualizado se já estiver faturado ou cancelado (status 1 ou 3) - Preço, desconto e frete são distribuídos entre os itens

Mapeamento de status:

Status WooCommerce	`PE_STATUS`	`PE_FINANCEIRO`
`cancelled`, `refunded`, `failed`	3 (cancelado)	2
`processing`, `completed`	0 (aberto)	1 (pago)
Demais	0 (aberto)	0 (pendente)

5. Categorias (Master Key → WooCommerce)¶

Sincroniza a árvore de categorias (CATEGPROD) de forma recursiva, respeitando a hierarquia pai/filho. Somente categorias modificadas são enviadas.

O slug da categoria é gerado automaticamente combinando os slugs da hierarquia (ex.: roupas-camisetas)
O ID da categoria no WooCommerce é salvo na tabela CAMPOS do Master Key
A descrição SEO da categoria (CP_SEO_DESCRICAO) é enviada como description

6. Produtos (Master Key → WooCommerce)¶

Sincroniza produtos modificados. Executa após Categorias e Pedidos.

Produtos sem grade → tipo simple
Produtos com grade → tipo variable (produto pai) + variações (variations)
Detecta produtos que existem no WooCommerce mas foram removidos do Master Key e os exclui
Detecta grades removidas e as exclui individualmente
Detecta produtos que estavam em uso mas nunca foram enviados ao WooCommerce e força o reenvio

Status do produto: - publish — ativo e disponível (EC_DISP = 'S') e com preço > 0 - private — inativo, indisponível ou sem preço

Campos enviados:

Campo Master Key	Campo WooCommerce	Nível	Descrição
`PR_CODIGO`	`sku`	Produto	SKU
`EC_NOMEPROD` / `PR_NOME`	`name`	Produto	Nome
`PR_REFTECN`	`description`	Produto	Referência técnica / descrição
`PR_NOMERES` / `PR_NOME`	`short_description`	Produto	Descrição curta
`VLR_UNIT` / `VLR_UNIT_2`	`regular_price`	Produto	Preço normal
`VALOR_PROMO` (dentro do período)	`sale_price`	Produto	Preço promocional
`PR_PBRUTO`	`weight`	Produto	Peso bruto (kg)
`EC_ALTURA`	`dimensions.height`	Produto	Altura (cm)
`EC_PROFUNDIDADE`	`dimensions.length`	Produto	Comprimento (cm)
`EC_LARGURA`	`dimensions.width`	Produto	Largura (cm)
`MA_NOME`	atributo `Marca`	Produto	Marca
Especificações do produto	atributos extras	Produto	Especificações como atributos
`CO_NOME`	atributo `Cor` (variation=true)	Produto	Cor para variação
`TM_NOME`	atributo `Tamanho` (variation=true)	Produto	Tamanho para variação
`PR_CODIGO` + `-` + `FG_SEQ`	`sku`	Variação	SKU da grade

7. Imagens (Master Key → WooCommerce)¶

Envia imagens dos produtos. Executa após Produtos.

Controla as imagens por hash MD5: se uma imagem já foi enviada com o mesmo MD5, reutiliza o ID no WooCommerce sem reenviar
Imagens novas são primeiramente enviadas ao AWS S3 (obtendo URL pública), depois vinculadas ao produto via PUT products/{id}?_method=PUT
Após o vínculo bem-sucedido, o arquivo temporário é removido do S3
Para produtos com grade, cada variação recebe sua imagem principal separadamente via PUT variations/{id}
Detecta imagens removidas de produtos e atualiza o produto para refletir o conjunto atual

Tabelas e campos relevantes¶

Tabela	Campo	Função
`CAMPOS`	`CAMPO` / `VALOR`	Armazena IDs externos (produto, variação de grade, categoria, imagem por MD5) vinculados aos códigos internos
`ECOMMERCE`	`EC_DISP`	Produto disponível para venda online (`S`/`N`)
`ECOMMERCE`	`EC_NOMEPROD`	Nome alternativo para e-commerce (se vazio, usa `PR_NOME`)
`ECOMMERCE`	`EC_MARGEMEST`	Margem de segurança de estoque (descontada do saldo)
`ECOMMERCE`	`EC_ALTURA/LARGURA/PROFUNDIDADE`	Dimensões para frete
`PRODUTOS`	`PR_REFTECN`	Referência técnica — usada como `description` no WooCommerce
`PRODUTOS`	`PR_NOMERES`	Nome resumido — usado como `short_description`
`CATEGPROD`	`CP_SEO_DESCRICAO`	Descrição SEO da categoria enviada ao WooCommerce

Perguntas frequentes do suporte¶

"O ciclo inicia mas aborta sem sincronizar nada" → Verifique se Consumer Key e Consumer Secret estão corretos. Confirme também se as Filiais de Estoque, Praça e Atividade estão configuradas.

"Produto não está sendo enviado para o WooCommerce" → Verifique se EC_DISP <> 'N' e PR_INATIVO <> 'S'. Confirme que o produto tem preço configurado — produtos sem preço são enviados como private.

"Produto foi excluído do Master Key mas ainda aparece no WooCommerce" → O sistema detecta automaticamente produtos que existem no WooCommerce mas não estão mais em uso no Master Key e os exclui no próximo ciclo. Se não ocorreu, verifique o log da etapa de Produtos para erros de exclusão.

"Estoque está errado no WooCommerce" → O estoque é sincronizado junto com os produtos. Verifique quais filiais estão em Filiais de Estoque e a margem de segurança (EC_MARGEMEST).

"Imagem não aparece no WooCommerce" → Verifique se o produto já foi sincronizado. Se sim, confirme que a imagem está cadastrada no banco de imagens do Master Key e vinculada ao produto. Verifique o campo Imagem na aba de Atualização — se não estiver marcado, a etapa de Imagens não executa.

"Pedido importado sem cliente vinculado" → A integração busca o cliente por CPF, CNPJ, RG ou e-mail. Se o pedido no WooCommerce tiver esses campos vazios, o cliente não é localizado. Verifique se o cadastro do cliente no WooCommerce está completo.

"Cliente com cidade 'Cidade Inexistente!'" → A cidade informada no WooCommerce não foi encontrada na tabela de cidades do Master Key e o serviço de CEP não resolveu. Atualize manualmente o cadastro no Master Key.