Loja Integrada — Integração com E-commerce¶

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

O que é¶

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

O fluxo é bidirecional: - Loja Integrada → Master Key: clientes e pedidos - Master Key → Loja Integrada: marcas, categorias, produtos, preços, estoque e imagens

Pré-requisitos¶

Chave de API da Loja Integrada (obtida no painel em Configurações → Dados da Loja → Chave de API)
Banco de dados do Master Key acessível pelo computador onde o aplicativo roda
A URL base da API (https://api.awsli.com.br/v1/) é configurada automaticamente pelo aplicativo

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 é
Chave de API	Chave de autenticação da Loja Integrada (usada em todas as requisições junto com a chave do aplicativo)

A autenticação usa dois parâmetros em todas as chamadas: chave_api (sua chave) e chave_aplicacao (chave interna do integrador, fixa).

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. Se vazias, o ciclo aborta com erro.

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

Clientes¶

Campo	O que é
Vendedor	Vendedor padrão atribuído ao cliente cadastrado
Praça	Praça padrão do cliente
Atividade	Atividade padrão do cliente

Vendedor, Praça e Atividade são obrigatórios para clientes. O ciclo aborta se algum não estiver configurado.

Produtos¶

Campo	O que é
Tabela de Preço	Tabela usada para o preço de venda enviado. `Cadastro de Produtos` usa o preço direto do cadastro
Produto Indisponível	Define o comportamento quando `EC_DISP = 'N'`: Inativar produto (padrão) ou Manter ativo
Enviar Similares	Envia produtos similares do Master Key como opções/variantes na Loja Integrada

Fluxo de Sincronização¶

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

Clientes ──► Pedidos ──┐
                       ▼
Marcas ────────────► Produtos ──► Imagens
                       │
Categorias ────────────┘
                       │
                       └──► Estoque

1. Clientes (Loja Integrada → Master Key)¶

Importa clientes modificados desde a última sincronização (paginado, 50 por página).

Para cada cliente: - Busca no Master Key por ID externo da Loja Integrada - Se não encontrado por ID, busca por CPF/CNPJ ou e-mail - Se ainda não encontrado, cria um novo cliente com tipo C e consumidor S - Importa o endereço padrão e endereços adicionais - Se a cidade/UF não existir na tabela do Master Key, consulta o serviço de CEP. Se não resolver, registra UF=!! e Cidade=Cidade Inexistente!

Campos importados:

Campo Loja Integrada	Campo Master Key	Descrição
`nome`	`CL_NOME`	Nome do cliente
`email`	`CL_EMAIL`	E-mail
`cpf` / `cnpj`	`CL_CPF` ou `CL_CGC`	CPF ou CNPJ
`telefone_principal`	`CL_FONE`	Telefone
`endereco`	`CL_ENDERECO`	Logradouro
`numero`	`CL_NRO`	Número
`complemento`	`CL_COMPL`	Complemento
`bairro`	`CL_BAIRRO`	Bairro
`cep`	`CL_CEP`	CEP
`estado` + `cidade`	`CL_UF` + `CL_CIDADE`	Estado e cidade

2. Pedidos (Loja Integrada → Master Key)¶

Importa pedidos modificados desde a última sincronização (20 por página). Executa após clientes.

Atenção: o pedido exige que o cliente já exista no Master Key. Se o cliente não for encontrado, o pedido não é importado e é registrado erro.

Para cada pedido: - Busca o cliente pelo ID externo (vinculado na etapa de Clientes) - Cria ou atualiza o pedido no Master Key - Pedido existente não é atualizado se já estiver faturado/cancelado (status 1 ou 3) sem alterações, ou se já tiver saídas vinculadas - A forma de pagamento é registrada na observação do pedido - Desconto e frete são distribuídos proporcionalmente entre os itens

Mapeamento de status:

Situação Loja Integrada	`PE_STATUS`	`PE_FINANCEIRO`
`pedido_cancelado`, `pagamento_devolvido`, `pedido_chargeback`	3 (cancelado)	2
`pedido_pago`, `pedido_enviado`, `pedido_efetuado`	0 (aberto)	1 (pago)
Demais situações	0 (aberto)	0 (pendente)

Campos importados:

Campo Loja Integrada	Campo Master Key	Descrição
`numero`	`PE_PEDEXTERNO`	Número do pedido na Loja Integrada
`data_criacao`	`PE_DATA` / `PE_HORA`	Data e hora de criação
`valor_total`	`PE_VLRTOTAL`	Valor total
`valor_envio`	`PE_VLFRETE`	Valor do frete
`endereco_entrega`	`PE_OBS`	Endereço de entrega + forma de pagamento na observação

3. Marcas (Master Key → Loja Integrada)¶

Sincroniza marcas de produtos (MARCAS) modificadas desde a última sincronização. Executa em paralelo com Clientes/Pedidos.

Campos enviados: nome, apelido (slug do nome), descricao, ativo (MA_INATIVO = 'N').

4. Categorias (Master Key → Loja Integrada)¶

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

O ID da categoria na Loja Integrada é salvo na tabela CAMPOS do Master Key.

5. Produtos (Master Key → Loja Integrada)¶

Sincroniza produtos modificados. Executa após Marcas e Categorias. Para cada produto, além dos dados cadastrais, envia os preços via endpoint separado (produto_preco).

A Loja Integrada usa três tipos de produto:

Tipo	Quando	Descrição
`normal`	Produto sem similares	Produto padrão sem variações
`atributo`	Produto pai de similares	Produto principal, agrupa as opções
`atributo_opcao`	Produto filho (similar)	Variação de um produto pai

Quando Enviar Similares está ativo, o sistema cria automaticamente uma "Grade Padrão" chamada Variações na Loja Integrada (caso não exista) para vincular os similares como variações.

Campos enviados:

Campo Master Key	Campo Loja Integrada	Descrição
`PR_CODIGO`	`sku`	SKU / código interno
`EC_NOMEPROD` / `PR_NOME`	`nome`	Nome do produto
`PR_REFTECN`	`descricao_completa`	Referência técnica como descrição (em `<pre>`)
`PR_MARCA`	`marca`	Link para a marca sincronizada
`PR_NCM`	`ncm`	NCM
`PR_PBRUTO`	`peso`	Peso bruto (kg)
`EC_ALTURA`	`altura`	Altura (cm)
`EC_LARGURA`	`largura`	Largura (cm)
`EC_PROFUNDIDADE`	`profundidade`	Profundidade (cm)
`PR_CODBARRA`	`gtin`	Código de barras
`EC_DESTACAR`	`destaque`	Produto em destaque
`PR_INATIVO` + `EC_DISP`	`ativo`	Ativo na loja (conforme configuração de Produto Indisponível)
Categorias do produto	`categorias`	Links para as categorias sincronizadas

Preços (endpoint produto_preco):

Campo Master Key	Campo Loja Integrada	Descrição
`VLR_UNIT`	`cheio`	Preço de venda
`PR_PRECOCUST`	`custo`	Preço de custo (0 se não informado)
`VALOR_PROMO` (dentro do período)	`promocional`	Preço promocional (0 fora do período)

6. Imagens (Master Key → Loja Integrada via AWS S3)¶

Envia imagens dos produtos. Executa após Produtos.

O processo é em duas etapas: 1. Faz upload da imagem para o AWS S3 (obtendo uma URL temporária de 1 dia) 2. Envia a URL S3 para a Loja Integrada via produto_imagem

Somente imagens de produtos com EC_DISP in ('S','I') e não inativos são enviadas. O nome do arquivo no S3 é gerado como MD5 do CNPJ + código da imagem.

Imagens já enviadas anteriormente não são reenviadas (vinculação controlada pela tabela CAMPOS).

7. Estoque (Master Key → Loja Integrada)¶

Atualiza o estoque dos produtos via endpoint produto_estoque. Executa após Produtos.

Busca produtos com saldo de estoque modificado desde a última sincronização
Se EC_DISP = 'S': envia o saldo real das filiais menos a margem de segurança (EC_MARGEMEST). Valores negativos são enviados como zero
Se EC_DISP <> 'S': envia estoque 0

Parâmetros sempre enviados: gerenciado=true, situacao_em_estoque=0, situacao_sem_estoque=-1.

Tabelas e campos relevantes¶

Tabela	Campo	Função
`CAMPOS`	`CAMPO` / `VALOR`	Armazena IDs externos (produto, marca, categoria, imagem) vinculados aos códigos internos
`ECOMMERCE`	`EC_DISP`	Produto disponível online (`S`/`N`/`I`)
`ECOMMERCE`	`EC_NOMEPROD`	Nome alternativo para e-commerce
`ECOMMERCE`	`EC_MARGEMEST`	Margem de segurança de estoque
`ECOMMERCE`	`EC_DESTACAR`	Produto em destaque na loja
`ECOMMERCE`	`EC_ALTURA/LARGURA/PROFUNDIDADE`	Dimensões para frete
`PRODUTOS`	`PR_REFTECN`	Referência técnica — usada como descrição completa na loja
`MARCAS`	`MA_INATIVO`	Marca inativa (`S`/`N`) — inativas são enviadas como `ativo=false`
`CATEGPROD`	`CP_CATEG_MESTRE`	Categoria pai — usada para montar a hierarquia

Perguntas frequentes do suporte¶

"O ciclo inicia mas aborta sem sincronizar nada" → Verifique se Filiais de Estoque, Vendedor, Praça e Atividade (Clientes) estão configurados. Qualquer um destes campos vazio aborta o ciclo com erro.

"Pedido não foi importado — erro 'Cliente não encontrado'" → O pedido exige que o cliente já esteja no Master Key. Certifique-se de que a etapa de Clientes está funcionando. Se o cliente foi criado manualmente no Master Key sem passar pela integração, ele não terá o vínculo de ID externo — vincule manualmente na tabela CAMPOS ou aguarde o próximo ciclo de Clientes.

"Produto não aparece na Loja Integrada" → Verifique se EC_DISP <> 'N' e PR_INATIVO <> 'S'. Confirme também se a Chave de API está correta nas configurações.

"Produto está ativo na loja mas sem estoque disponível" → Verifique a configuração Produto Indisponível. Se estiver em Manter ativo, o produto permanece ativo mesmo quando EC_DISP = 'N'. O estoque enviado para produtos indisponíveis é sempre 0.

"Similar não está aparecendo como variação" → Confirme que Enviar Similares está marcado. Verifique se os produtos estão corretamente relacionados como similares no cadastro do Master Key e se o produto pai já foi sincronizado antes do filho.

"Estoque desatualizado na Loja Integrada" → O estoque é sincronizado separadamente dos produtos. Verifique os logs da etapa de Estoque. Confirme se as filiais corretas estão selecionadas em Filiais de Estoque.

"Imagem não aparece na loja" → Verifique se o produto já foi sincronizado (imagens dependem do produto existir na Loja Integrada). Confirme que a imagem está cadastrada no banco de imagens do Master Key e que o produto tem EC_DISP in ('S','I'). Verifique logs da etapa de Imagens para erros de upload no AWS S3.

"Preço promocional não está aparecendo" → O preço promocional só é enviado se VALOR_PROMO > 0 e a data atual estiver dentro do período de promoção (DT_PROMO_INI a DT_PROMO_FIM). Fora do período, o valor enviado é 0, limpando a promoção na loja.