NuvemShop — Integração com E-commerce¶
Aplicativo externo
IntegraNuvemShop.exe| Sincronização automática em intervalo configurável
O que é¶
A Integração NuvemShop é um aplicativo standalone (separado do Master Key) que sincroniza dados entre o Master Key e uma loja na plataforma de e-commerce NuvemShop. A sincronização ocorre em ciclos automáticos com execução paralela das etapas independentes.
O fluxo é bidirecional: - NuvemShop → Master Key: clientes e pedidos - Master Key → NuvemShop: categorias, produtos, variações, grades e imagens
Pré-requisitos¶
- URL base da loja NuvemShop e Token de API (obtidos no painel da loja em Configurações → Apps e integrações)
- 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://loja.lojavirtual.com.br/api/v1/123456) |
| Token | Token de autenticação Bearer fornecido pela NuvemShop |
Estoque¶
| Campo | O que é |
|---|---|
| Filiais de Estoque | Filiais cujos saldos somam para calcular o estoque enviado |
Filiais de estoque são obrigatórias. 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 |
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. Cadastro de Produtos usa o preço direto do cadastro |
| Enviar Tamanhos | Envia as grades de tamanho como variações na NuvemShop |
| Descrição dos Tamanhos | Nome do atributo de tamanho exibido na loja (ex.: Tamanho) |
| Enviar Cores | Envia as grades de cor como variações na NuvemShop |
| Descrição das Cores | Nome do atributo de cor exibido na loja (ex.: Cor) |
Campos de Inserção / Atualização¶
A tela apresenta duas abas de campos configuráveis: - Inserção: campos enviados quando o produto ainda não existe na NuvemShop - Atualização: campos enviados ao atualizar um produto já existente
Fluxo de Sincronização¶
A cada ciclo, o aplicativo executa as etapas abaixo. As etapas Clientes, Pedidos e Categorias rodam em paralelo; Produtos aguarda Categorias e Pedidos finalizarem; Imagens aguarda Produtos.
1. Clientes (NuvemShop → Master Key)¶
Importa clientes modificados desde a última sincronização (50 por página, paginado).
Para cada cliente:
- Busca no Master Key por CPF/CNPJ ou 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
- 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 NuvemShop | Campo Master Key | Descrição |
|---|---|---|
name |
CL_NOME |
Nome do cliente |
email |
CL_EMAIL |
|
identification |
CL_CPF ou CL_CGC |
CPF (11 dígitos) ou CNPJ |
phone |
CL_FONE |
Telefone |
default_address.address |
CL_ENDERECO |
Logradouro |
default_address.number |
CL_NRO |
Número |
default_address.floor |
CL_COMPL |
Complemento |
default_address.locality |
CL_BAIRRO |
Bairro |
default_address.zipcode |
CL_CEP |
CEP |
default_address.province + city |
CL_UF + CL_CIDADE |
Estado e cidade |
2. Pedidos (NuvemShop → Master Key)¶
Importa pedidos modificados desde a última sincronização (50 por página, paginado). Executa após clientes para garantir que o cadastro do cliente já exista.
Para cada pedido: - Busca o cliente pelo CPF/CNPJ ou e-mail do pedido - Cria ou atualiza o pedido no Master Key - Um pedido existente não é atualizado se já estiver no status 1 (faturado) e sem alterações - Desconto e frete são distribuídos proporcionalmente entre os itens
Mapeamento de status:
| Status NuvemShop | PE_STATUS |
PE_FINANCEIRO |
|---|---|---|
cancelled |
3 (cancelado) | 2 |
open + authorized/paid |
0 (aberto) | 1 (pago) |
open + abandoned/refunded/voided |
0 (aberto) | 2 (cancelado financeiro) |
open + demais |
0 (aberto) | 0 (pendente) |
Campos importados:
| Campo NuvemShop | Campo Master Key | Descrição |
|---|---|---|
id |
PE_PEDEXTERNO |
ID do pedido na NuvemShop |
created_at |
PE_DATA / PE_HORA |
Data e hora de criação |
total |
PE_VLRTOTAL |
Valor total |
shipping_cost_customer |
PE_VLFRETE |
Valor do frete |
shipping_address |
PE_OBS |
Endereço de entrega gravado na observação |
3. Categorias (Master Key → NuvemShop)¶
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.
O ID da categoria na NuvemShop é salvo na tabela CAMPOS do Master Key para referência futura dos produtos.
4. Produtos (Master Key → NuvemShop)¶
Sincroniza produtos modificados. Executa após Categorias e Pedidos. A NuvemShop usa um modelo de Produto Pai + Variações:
- Produto Pai: contém nome, descrição, marca, categorias e atributos (cor/tamanho)
- Variação: contém SKU, preço, estoque, dimensões, código de barras e valores dos atributos
Um produto sem grade gera 1 pai + 1 variação. Um produto com grade gera 1 pai + N variações (uma por combinação tamanho/cor).
Campos enviados:
| Campo Master Key | Campo NuvemShop | Nível | Descrição |
|---|---|---|---|
EC_NOMEPROD / PR_NOME |
name |
Pai | Nome do produto |
PR_REFTECN |
description |
Pai | Referência técnica / descrição |
MA_NOME |
brand |
Pai | Marca |
PR_INATIVO + EC_DISP |
published |
Pai | Publicado na loja |
PR_CODIGO (+ grades) |
sku |
Variação | SKU (ex.: 100-P-AZUL) |
PR_PBRUTO |
weight |
Variação | Peso bruto (kg) |
EC_ALTURA |
height |
Variação | Altura (cm) |
EC_LARGURA |
width |
Variação | Largura (cm) |
EC_PROFUNDIDADE |
depth |
Variação | Profundidade (cm) |
PR_PRECOCUST |
cost |
Variação | Preço de custo |
VLR_UNIT |
price |
Variação | Preço de venda |
VALOR_PROMO (dentro do período) |
promotional_price |
Variação | Preço promocional |
PR_CODBARRA / FG_CODBARRA |
barcode |
Variação | Código de barras |
Saldo das filiais - MARGEM |
stock |
Variação | Estoque (mínimo zero) |
COR / TAMANHO |
values |
Variação | Valores dos atributos de grade |
O preço promocional só é enviado se a data atual estiver dentro do período de promoção (
DT_PROMO_INIaDT_PROMO_FIM). Fora do período, envianull, limpando o preço promocional na loja.
5. Imagens (Master Key → NuvemShop)¶
Envia imagens dos produtos diretamente pela API como Base64 (não usa FTP). Executa após Produtos.
- Busca imagens modificadas no banco de imagens do Master Key
- Converte o blob para Base64 e envia via
POST /products/{id}/images - Ao atualizar uma imagem já enviada, usa
PUTcom o ID externo salvo - Se a API retornar
Invalid image ID, remove o vínculo e reenvia como nova imagem - O nome do arquivo é gerado como MD5 do CNPJ da filial + código da imagem
Tabelas e campos relevantes¶
| Tabela | Campo | Função |
|---|---|---|
CAMPOS |
CAMPO / VALOR |
Armazena IDs externos (produto pai, variação, categoria, imagem) 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 |
PRODUTOS |
PR_REFTECN |
Referência técnica — usada como descrição do produto na NuvemShop |
CATEGPROD |
CP_CATEG_MESTRE |
Categoria pai — usada para montar a hierarquia enviada à NuvemShop |
IMG_PRODUTO |
IMAGEM |
Blob da imagem do produto enviada via API |
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.
"Produto não está sendo enviado para a NuvemShop"
→ Verifique se EC_DISP = 'S' e PR_INATIVO <> 'S' no cadastro do produto. Somente produtos ativos e disponíveis são enviados.
"Produto com grade está aparecendo sem variações" → Confirme se Enviar Tamanhos e/ou Enviar Cores estão marcados nas configurações. Sem isso, o produto é enviado como variação única.
"Estoque está errado na NuvemShop"
→ 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 o cliente correto"
→ A integração busca o cliente por CPF/CNPJ ou e-mail. Se o campo contact_identification e contact_email do pedido na NuvemShop estiverem vazios, o pedido será criado sem vínculo de cliente.
"Cliente com cidade 'Cidade Inexistente!'" → A cidade informada pelo cliente na NuvemShop 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 NuvemShop" → Verifique se o produto já foi sincronizado (imagens dependem do produto existir na NuvemShop). Confira o log do ciclo para erros na etapa de Imagens. A imagem precisa estar cadastrada no banco de imagens do Master Key vinculada ao produto.