Magento — Integração com E-commerce¶

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

O que é¶

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

O fluxo é bidirecional: - Magento → Master Key: clientes e pedidos - Master Key → Magento: categorias, atributos (cores e tamanhos), produtos, especificações, promoções, imagens e estoque

Opcionalmente, a integração também envia notas fiscais do Master Key para o Magento.

Pré-requisitos¶

URL da API REST do Magento (ex.: https://loja.com.br/index.php/rest/V1/)
Token de autenticação Bearer ou Nome de usuário e Senha com permissão de API no Magento
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 API REST do Magento (ex.: `https://loja.com.br/index.php/rest/V1/`)
URL Back	URL de backoffice do Magento (usada em algumas operações administrativas). Padrão: igual à URL principal
Token	Token Bearer de autenticação (se informado, dispensa Nome e Senha)
Nome	Usuário do Magento (usado para gerar token se o campo Token estiver vazio)
Senha	Senha do usuário Magento

Se Token estiver preenchido, o campo de Nome e Senha fica oculto. Se vazio, o sistema gera um token automaticamente com Nome e Senha a cada ciclo.

Produtos¶

Campo	O que é
Tabela de Preço	Tabela usada para o campo `price`. `Preço de Venda` usa `PR_PRECOVEND`, `Preço de Venda 2` usa `PR_PRECOVEND2`
Enviar Estoque	Controla se o estoque é atualizado no Magento
Enviar Observação	Usa o campo `PR_OBS` como descrição do produto (se desmarcado, usa `PR_REFTECN`)
Obs. na Desc. Curta	Usa `PR_OBS` como descrição curta (se desmarcado, usa `PR_REFTECN`)
Enviar Especificações	Sincroniza especificações de produto como atributos no Magento
Enviar Promoções	Sincroniza preços promocionais no Magento
Referência como Marca	Usa `PR_CODALFA` (código de referência) como marca no Magento

Estoque¶

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

Pedidos¶

Campo	O que é
Vendedor	Código do vendedor padrão atribuído a cada pedido importado
Tipo de Frete	Tipo de frete padrão atribuído aos pedidos importados

Clientes¶

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

Imagens¶

Campo	O que é
Enviar para	Destino das imagens: FTP ou AWS S3

Notas Fiscais¶

Campo	O que é
Enviar Notas Fiscais	Quando ativo, envia XML das notas fiscais emitidas no Master Key para o Magento
E-mail de Cópia	Endereço que recebe cópia dos pedidos importados

Fluxo de Sincronização¶

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

Configs ──► Token ──► Clientes ──────────────────────────────────────┐
                  ──► Pedidos ───────────────────────────────────►  Estoque
                  ──► Categorias ──┐                                    ▲
                  ──► Cores ───────┼──► Produtos ──► Especificações     │
                  ──► Tamanhos ────┘           ├──► Promoções           │
                                               ├──► Imagens             │
                                               ├──► Imagens de Grades   │
                                               └───────────────────────┘
                                                        ▼
                                           (Pedidos) ──► Notas

Token aguarda Configs. Depois disso, Clientes, Pedidos, Categorias, Cores e Tamanhos iniciam em paralelo. Produtos aguarda Categorias, Cores e Tamanhos, e bloqueia Pedidos. Após Produtos: Especificações, Promoções, Imagens e Imagens de Grades em paralelo. Estoque aguarda Pedidos e Produtos. Notas aguarda Pedidos.

1. Configs + Token¶

Carrega parâmetros do sistema. Se o Token não estiver pré-configurado, gera um token de sessão autenticando com Nome e Senha via POST /integration/admin/token.

2. Clientes (Magento → Master Key)¶

Importa clientes modificados desde a última sincronização.

Para cada cliente: - Busca no Master Key por ID externo do Magento - Se não encontrado, busca por e-mail para evitar duplicatas - Cria ou atualiza o cadastro com endereço de cobrança e endereço de entrega - Resolve cidade/UF pelo código de estado informado; se não encontrar, consulta o serviço de CEP. Se ainda assim não resolver, registra UF=!! e Cidade=Cidade Inexistente!

3. Pedidos (Magento → Master Key)¶

Importa pedidos modificados desde a última sincronização, paginado. Executa em paralelo com Clientes.

Para cada pedido: - Localiza o cliente por CPF/CNPJ ou e-mail - Cria ou atualiza o pedido no Master Key - Pedido existente não é atualizado se já estiver faturado (status 1) - Impostos são somados ao preço unitário de cada item

Mapeamento de status:

Status Magento	`PE_STATUS`	`PE_FINANCEIRO`
`canceled`	3 (cancelado)	2
`processing`, `complete`	0 (aberto)	1 (pago)
Demais	0 (aberto)	0 (pendente)

4. Categorias (Master Key → Magento)¶

Sincroniza a árvore de categorias (CATEGPROD) de forma recursiva. O ID da categoria no Magento é salvo na tabela CAMPOS do Master Key.

5. Cores e Tamanhos (Master Key → Magento)¶

Sincroniza os valores de atributos de cor e tamanho como opções de atributos configuráveis no Magento, preparando o terreno para os produtos com grade.

6. Produtos (Master Key → Magento)¶

Sincroniza produtos modificados. Executa após Categorias, Cores e Tamanhos.

Produtos sem grade → tipo simple
Produtos com grade → tipo configurable (produto pai, visibility=4) + produtos simple filhos (um por grade, visibility=1, SKU = PR_CODIGO|FG_SEQ)
O produto configurável vincula os filhos pelos atributos de cor e tamanho

Status: 1 = ativo, 2 = inativo (baseado em PR_INATIVO + EC_DISP).

Campos enviados:

Campo Master Key	Campo Magento	Descrição
`PR_CODIGO`	`sku`	SKU (produto simples)
`PR_CODIGO\|FG_SEQ`	`sku`	SKU (grade)
`EC_NOMEPROD` / `PR_NOME`	`name`	Nome do produto
`PT_VALORUNI` / `PR_PRECOVEND` / `PR_PRECOVEND2`	`price`	Preço conforme tabela
`PR_PBRUTO`	`weight`	Peso bruto (kg)
`PR_OBS` / `PR_REFTECN`	`description`	Descrição (conforme configuração)
`TM_NOME` + `CO_NOME`	opções do configurável	Tamanho e cor da grade

7. Especificações (Master Key → Magento)¶

Se Enviar Especificações estiver ativo, sincroniza as especificações dos produtos como atributos no Magento. Executa após Produtos.

8. Promoções (Master Key → Magento)¶

Se Enviar Promoções estiver ativo, sincroniza preços promocionais. O preço promocional só é enviado se a data atual estiver dentro do período (DT_PROMO_INI a DT_PROMO_FIM). Executa após Produtos.

9. Imagens (Master Key → Magento)¶

Envia imagens dos produtos para o Magento via FTP ou AWS S3. Executa após Produtos.

10. Imagens de Grades (Master Key → Magento)¶

Envia a imagem principal de cada variação de grade. Executa após Produtos.

11. Estoque (Master Key → Magento)¶

Atualiza o estoque dos produtos. Executa após Pedidos e Produtos.

Uma vez por dia reenvia automaticamente as alterações de estoque dos últimos 3 dias para compensar possíveis divergências
Nos demais ciclos, sincroniza apenas alterações desde a última sincronização
Envia 0 para produtos indisponíveis (EC_DISP <> 'S')

12. Notas Fiscais (Master Key → Magento)¶

Se Enviar Notas Fiscais estiver ativo, envia o XML das notas fiscais emitidas no Master Key para o Magento, vinculando ao pedido correspondente. Executa após Pedidos.

Tabelas e campos relevantes¶

Tabela	Campo	Função
`CAMPOS`	`CAMPO` / `VALOR`	Armazena IDs externos (produto, categoria, imagem, atributos) vinculados aos códigos internos
`ECOMMERCE`	`EC_DISP`	Produto disponível para venda online (`S`/`N`)
`ECOMMERCE`	`EC_NOMEPROD`	Nome alternativo para e-commerce
`PRODUTOS`	`PR_REFTECN`	Referência técnica — usada como descrição do produto (conforme configuração)
`PRODUTOS`	`PR_OBS`	Observação — pode ser usada como descrição ou descrição curta
`PRODUTOS`	`PR_CODALFA`	Código de referência — pode ser enviado como marca
`PRODUTOS`	`PR_INATIVO`	Produto inativo (`S`) → status 2 no Magento
`CATEGPROD`	`CP_CATEG_MESTRE`	Categoria pai — usada para montar a hierarquia

Perguntas frequentes do suporte¶

"O ciclo aborta com erro de autenticação" → Verifique se o Token está válido e não expirou. Se estiver usando Nome e Senha, confirme as credenciais. O Magento pode expirar tokens de sessão — neste caso, limpe o Token nas configurações para que o sistema regenere a cada ciclo.

"Produto não está sendo enviado para o Magento" → Verifique se EC_DISP = 'S' e PR_INATIVO <> 'S'. Confirme que a categoria do produto está configurada e já foi sincronizada.

"Produto com grade aparece sem variações" → Confirme se o parâmetro USA_GRADE está ativo para a filial. Verifique se as etapas de Cores e Tamanhos foram concluídas com sucesso antes de Produtos.

"Estoque está desatualizado no Magento" → Verifique se Enviar Estoque está marcado. O estoque é reenviado automaticamente uma vez por dia cobrindo os últimos 3 dias. Confirme também quais filiais estão em Filiais de Estoque.

"Nota fiscal não foi enviada ao Magento" → Confirme que Enviar Notas Fiscais está marcado. Verifique se o pedido correspondente já foi importado do Magento (a nota é vinculada pelo número de pedido externo). Confira o log da etapa de Notas.

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