Shopify — Integração com E-commerce¶

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

O que é¶

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

O fluxo é bidirecional: - Shopify → Master Key: clientes e pedidos - Master Key → Shopify: categorias (Smart Collections), produtos, variações, imagens e estoque

Pré-requisitos¶

URL base da loja Shopify e Token de acesso (obtidos no painel em Configurações → Apps e canais de vendas → 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 Shopify (ex.: `https://sua-loja.myshopify.com/admin/api`)
Token	Token de acesso da API (`X-Shopify-Access-Token`) fornecido pela Shopify

Estoque¶

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

Filiais de estoque são obrigatórias para as etapas de Produtos e Estoque. 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 com valor total > 0

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 campo `price` das variações. `Cadastro de Produtos` usa o preço direto do cadastro

Fluxo de Sincronização¶

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

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

Clientes e Categorias iniciam em paralelo. Pedidos aguarda Clientes. Produtos aguarda Categorias. Imagens aguarda Produtos. Estoque aguarda Pedidos e Produtos.

1. Clientes (Shopify → Master Key)¶

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

Para cada cliente: - Busca no Master Key por e-mail para evitar duplicatas - Se encontrado, atualiza o cadastro existente - Se não encontrado, cria um novo cliente com tipo C e consumidor S - Importa o endereço padrão e endereços adicionais - A Shopify não possui campo específico para número — o sistema tenta extrair o número separando o campo address1 por vírgula (ex.: Rua das Flores, 123 → rua Rua das Flores, número 123). Se não houver vírgula, registra S/N - Se a cidade/UF não existir na tabela do Master Key, consulta o serviço de CEP para resolver. Se ainda assim não resolver, registra UF=!! e Cidade=Cidade Inexistente!

Campos importados:

Campo Shopify	Campo Master Key	Descrição
`first_name` + `last_name`	`CL_NOME`	Nome completo do cliente
`email`	`CL_EMAIL`	E-mail
`phone`	`CL_FONE`	Telefone (remove o prefixo `+55`)
`default_address.address1`	`CL_ENDERECO`	Logradouro (parte antes da vírgula, se houver)
`default_address.address1` (parte após vírgula)	`CL_NRO`	Número (extraído do mesmo campo de endereço)
`default_address.address2`	`CL_BAIRRO`	Bairro
`default_address.zip`	`CL_CEP`	CEP
`default_address.province_code` + `city`	`CL_UF` + `CL_CIDADE`	Estado e cidade

2. Pedidos (Shopify → Master Key)¶

Importa pedidos com qualquer status (status=any) modificados desde a última sincronização. Executa após Clientes.

Para cada pedido: - Busca o cliente pelo e-mail presente no pedido - Se não encontrado por e-mail, busca pelo ID externo do cliente vinculado na etapa de Clientes - Cria ou atualiza o pedido no Master Key - Pedido existente não é atualizado se já estiver nos status 1 (faturado) ou 3 (cancelado) - Pedidos com cancelled_at preenchido que ainda não existem no Master Key são ignorados (não importa pedido já cancelado) - Pedidos com grade geram registros na tabela PEDDGRADE - Se o cliente não tiver CPF/CNPJ, o sistema consulta a API GraphQL da Shopify para buscar extensões de localização do pedido (campo localizationExtensions) e preenche CPF (11 dígitos) ou CNPJ conforme o tamanho - Impostos dos itens (tax_lines) são somados ao preço unitário proporcionalmente - O endereço de entrega é gravado no campo de observação do pedido

Além de importar, a etapa também cancela pedidos no Master Key quando o status do pedido correspondente na Shopify mudar para cancelled_at preenchido.

Mapeamento de status:

Situação Shopify	`PE_STATUS`	`PE_FINANCEIRO`
`cancelled_at` preenchido	3 (cancelado)	2
`financial_status = paid` ou `authorized`	0 (aberto)	1 (pago)
Demais situações	0 (aberto)	0 (pendente)

Campos importados:

Campo Shopify	Campo Master Key	Descrição
`id`	`PE_PEDEXTERNO`	ID do pedido na Shopify
`created_at`	`PE_DATA` / `PE_HORA`	Data e hora de criação
`current_total_price`	`PE_VLRTOTAL`	Valor total
`shipping_address`	`PE_OBS`	Endereço de entrega gravado na observação
`line_items[].price` + impostos	`PI_VLUNITARIO`	Preço unitário com impostos incluídos
`line_items[].quantity`	`PI_QUANTIDADE`	Quantidade
`line_items[].total_discount`	`PI_VLDESC`	Desconto do item

3. Categorias (Master Key → Shopify)¶

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

As categorias são criadas na Shopify como Smart Collections com uma regra automática do tipo product_type equals <nome da categoria>. Produtos são vinculados às coleções pelo campo product_type, que recebe o nome da categoria no momento do envio do produto.

O ID da coleção na Shopify é salvo na tabela CAMPOS do Master Key para referência futura.

4. Produtos (Master Key → Shopify)¶

Sincroniza produtos modificados. Executa após Categorias. A Shopify usa um modelo de Produto (pai) + Variações:

Produto (pai): contém nome, descrição (body_html), tipo do produto (product_type = nome da categoria), status e dimensões como metafields
Variação: contém SKU, preço, peso, opção de tamanho e cor, código de barras e inventory_item_id

Um produto sem grade gera 1 produto + 1 variação. Um produto com grade gera 1 produto + N variações (uma por combinação tamanho/cor), com as opções Tamanho e Cor declaradas no produto pai.

Obrigatórios: dimensões (largura, altura, profundidade) e categoria. O ciclo lança erro para o produto se qualquer um estiver ausente.

Campos enviados:

Campo Master Key	Campo Shopify	Nível	Descrição
`EC_NOMEPROD` / `PR_NOME`	`title`	Produto	Nome do produto
`PR_REFTECN`	`body_html`	Produto	Referência técnica / descrição
`CP_NOME` (categoria)	`product_type`	Produto	Tipo do produto — vincula à Smart Collection
`PR_INATIVO` + `EC_DISP`	`status`	Produto	`active` (ativo + disponível) ou `archived` (demais)
`EC_LARGURA`	metafield `width`	Produto	Largura (cm) — enviado apenas na inserção
`EC_ALTURA`	metafield `height`	Produto	Altura (cm) — enviado apenas na inserção
`EC_PROFUNDIDADE`	metafield `length`	Produto	Profundidade (cm) — enviado apenas na inserção
`VLR_UNIT`	`price`	Variação	Preço de venda
`PR_CODBARRA` / `FG_CODBARRA`	`sku`	Variação	Código de barras como SKU
`PR_PBRUTO`	`weight` + `grams`	Variação	Peso bruto (kg e gramas)
`TAMANHO`	`option1`	Variação	Tamanho (para produtos com grade)
`COR`	`option2`	Variação	Cor (para produtos com grade)

5. Imagens (Master Key → Shopify)¶

Envia imagens dos produtos. Executa após Produtos.

Busca imagens modificadas no banco de imagens do Master Key
Converte o blob para Base64 e envia diretamente via POST /products/{id}/images.json
Para imagens sem grade: define a posição (position) na galeria do produto
Para imagens de grade (cor): vincula a imagem à variação correspondente via variant_ids
Imagens já enviadas não são reenviadas (vínculo controlado pela tabela CAMPOS)

6. Estoque (Master Key → Shopify)¶

Atualiza o estoque via endpoint inventory_levels/set. Executa após Pedidos e Produtos.

Na primeira execução, detecta automaticamente o location_id padrão da loja buscando os níveis de estoque do produto (GET inventory_levels.json?inventory_item_ids=...) e armazena na tabela CAMPOS
Nos ciclos seguintes reutiliza o location_id já armazenado
Soma o saldo das filiais configuradas; desconta a margem de segurança (MARGEM)
Valores negativos são enviados como zero

Tabelas e campos relevantes¶

Tabela	Campo	Função
`CAMPOS`	`CAMPO` / `VALOR`	Armazena IDs externos (produto pai, variação, categoria, imagem, `inventory_item_id`, `location_id`) 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_ALTURA/LARGURA/PROFUNDIDADE`	Dimensões para frete — obrigatórias na Shopify
`PRODUTOS`	`PR_REFTECN`	Referência técnica — usada como `body_html` do produto na Shopify
`PRODUTOS`	`PR_INATIVO`	Produto inativo (`S`/`N`) — inativo arquiva o produto na Shopify
`CATEGPROD`	`CP_CATEG_MESTRE`	Categoria pai — usada para montar a hierarquia recursiva
`PEDDGRADE`	`PG_PRODUTO` / `PG_ID1` / `PG_ID2`	Detalhe de grade dos itens do pedido importado
`IMG_PRODUTO`	`IMAGEM`	Blob da imagem do produto enviada via Base64

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 nas configurações do aplicativo. Qualquer campo vazio aborta o ciclo com erro.

"Produto não está sendo enviado para a Shopify" → Verifique se EC_DISP = 'S' e PR_INATIVO <> 'S' no cadastro do produto. Confirme também se as dimensões (Largura, Altura, Profundidade) e a Categoria estão preenchidas — ambas são obrigatórias na Shopify.

"Produto com grade aparece sem as variações de tamanho/cor" → Confirme se o produto tem grades cadastradas com combinações de tamanho e cor no Master Key. Produtos sem grade são enviados com uma única variação; as opções Tamanho e Cor só são criadas quando há grade.

"Estoque está errado na Shopify" → Verifique quais filiais estão em Filiais de Estoque. O estoque enviado é a soma dos saldos das filiais selecionadas menos a margem de segurança (MARGEM). Valores negativos são enviados como zero.

"Pedido importado sem CPF/CNPJ do cliente" → A integração busca CPF/CNPJ via extensões de localização da API GraphQL da Shopify no momento da importação do pedido. Se o campo localizationExtensions estiver vazio no pedido Shopify, o CPF/CNPJ não será preenchido — atualize manualmente no Master Key.

"Pedido da Shopify não entrou no Master Key" → Verifique se o produto dos itens do pedido já foi sincronizado (a integração busca o produto pelo variant_id ou product_id). Se o produto não for encontrado, o pedido lança erro. Sincronize os produtos primeiro e tente novamente.

"Cliente com cidade 'Cidade Inexistente!'" → A cidade informada pelo cliente na Shopify 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 após a importação.

"Imagem não aparece na Shopify" → Verifique se o produto já foi sincronizado (imagens dependem do produto existir na Shopify). Confira o log do ciclo para erros na etapa de Imagens. A imagem precisa estar cadastrada no banco de imagens do Master Key e vinculada ao produto.

"Categoria não está aparecendo na Shopify" → As categorias são criadas como Smart Collections com regra por product_type. Verifique se a categoria foi modificada recentemente (a etapa só envia categorias alteradas desde a última sincronização). Para forçar o reenvio, atualize a categoria no Master Key.