Ir para o conteúdo principal

Nuvemshop

SOBRE O NUVEMSHOP

A NUVEMSHOP é um site e-commerce que permite criar sua própria loja online auto gerenciável, sem a necessidade de conhecimentos técnicos. Ela oferece uma solução tecnológica pensada em micro, pequenas, médias e grandes empresas. 

O conteúdo aqui incluso referencia-se a uma integração entre ERP X NUVEMSHOP, permitindo ao usuário novas opções de recursos para melhor organização do seu negócio. 

Siga os passos abaixo, sem pular nenhuma etapa, e no fim poderá utilizar essa melhoria corretamente. 

LOGIN NO NUVEMSHOP
  • Acesse o Endereço: http://partners.nuvemshop.com.br/
  • Para uso interno (Ema) utilize as seguintes credenciais: 
    • Usuário: desenvolvimento@emasoftware.com.br
    • Senha: Dev@Ema#2025

Caso o cliente não possua uma conta, é necessário criar. Importante ressaltar que a Ema é parceira do NS, então a conta disponibilizada é uma conta DEMO para testes. Mesmo que apareçam avisos de plano ou encerramento de teste gratis, a conta possui todas as funções necessárias para os testes com o ERP. 

image-1687279139909.png

  • Depois de logado, crie um aplicativo e uma loja;

O aplicativo é o responsável pela comunicação da API com a loja, neste exemplo é usado a loja 'Demo Casa das Maquinas', que é uma loja base para testes.

image-1688391186957.png

OBTENDO O TOKEN

image-1688390058855.png

Isso o levará para uma pagina onde estará o código para obter acesso a API. 

image-1688390237701.png

  • Copie o endereço CODE que está na URL e guarde para utilizar nos passos abaixo.
OBTENDO O TOKEN - API
{
"client_id": "7433",
"client_secret": "2e6156a1b496e8552cfc656e71e3c66d5db4e2b008ecf1eb",
"grant_type": "authorization_code",
"code": "e4a01f5ac80ab8f8d3e3c8ef8c3403df7447bbce"
}

Sendo:

  • "client_id" = Código do aplicativo;
  • "client_secret" = Código secreto gerado quando foi criado o aplicativo;
  • "grant_type": "authorization_code" = Fixo;
  • "code" = Código obtido no passo anterior;

image-1688390491339.png

Exemplo de retorno:

{
    "access_token": "7de79ca10bf0a3eaa059f6e226d4890202fd1ae9",
    "token_type": "bearer",
    "scope": "read_content,write_content,read_products,write_products,read_coupons,write_coupons,read_customers,write_customers,read_orders,write_orders,read_shipping,write_shipping,read_discounts,write_discounts,read_draft_orders,write_draft_orders,write_scripts,read_locations,write_locations,read_fulfillment_orders,write_fulfillment_orders",
    "user_id": 2847442
}

* Ao configurar as informações no POSTMAN, não é necessário informar nada nas abas de 'Params', 'Authorization', 'Headers' ets. Apenas o endereço POST e a aba 'Body': 

image-1688391432952.png

CONFIGURANDO A INTEGRAÇÃO NO ERP
  • Acessar ERP
  • Vendas 
  • Vendas móveis > Parâmetros 

image-1688392121178.png

  • Na aba 'Integração E-commerce', ao criar um novo registro, selecione a opção 'NUVEMSHOP': 
  • Os campos necessários para realizar a integração permitirão a edição, os demais campos estarão como 'somente leitura'.

image-1705667214183.png

Url do ambiente de teste: https://api.nuvemshop.com.br/v1/3324150

Token do ambiente de teste: bearer ea136f8dae7e7361fcb4dfd25c645da1c88df815

image-1688392620438.png

Importante!

  • No campo "TOKEN de acesso" é necessário colocar a descrição bearer + o token de acesso que conseguimos nos passos acima. 
  • *** Importante ressaltar que a descrição bearer deve ser em MINUSCULO e deve existir um ESPAÇO entre o bearer e o token de acesso.
  • Além das informações obrigatórias, não esqueça de configurar os campos das outras abas da configuração E-commerce como 'Configuração': 

image-1706551240749.png

Ao marcar o parâmetro 'Utiliza 'De/Para' na transportadora ao importar pedido para ERP, a aba 'Transportadoras' ficará visível para configuração. 

Marcando o parâmetro "Insere na observação do pedido os itens sem valor ou sem SKU", ao sincronizar o pedido do NUVEMSHOP para o ERP com itens sem SKU, ou seja, item criados diretamente no NUVEMSHOP, o sistema irá informar na observação do pedido importado. 

Ex: 

image-1706556813306.png

  • Aba 'Transportadoras'

image-1705667490287.png

  • Aba 'Estoque'

image-1689945523063.png

  • Aba 'Preço':

image-1706550914960.png

  • Aba 'Pedido':

image-1690995058992.png

E está pronto! integração concluída! 

INFORMAÇÕES ADICIONAIS: 
  • A implementação desta integração no ERP saiu na versão 17.9.0.614, tarefa #344356
  • Correções mais importante foram implementadas na release 17.13.4.620, então é aconselhável atualizar para essa versão caso essa integração for implementada em cliente. 
  • Segundo o retorno do suporte NUVEMSHOP, atualmente só é possível usar um e-mail de cadastro para cada loja. 
  • O token de acesso gerado só é valido por 5 minutos. Caso a configuração da integração E-commerce não seja concluída antes desse tempo, será necessário gerar um novo token de acesso, conforme os passos acima. 
ITEM = PRODUTO 

Vamos mostrar abaixo a relação de Item e Produto de ERP x Nuvemshop. Com a integração E-commerce devidamente configurada, acesse: 

  • Estoque> 
  • Itens> 
  • Novo> 

image-1689353763345.png

  • Ao criar um novo item, na aba 'Outros', marque a opção 'Exporta para NuvemShop'.

image-1705668134530.png

  • Com isso, finalize o cadastro e salve. 

Importante!

  • Quando for enviado o item para a loja, o sistema buscará pelo SKU se este item já existe no NUVEMSHOP. Caso não exista, criará um novo. Caso exista, irá atualizar o atual. 
  • Por padrão, os itens enviados do ERP estão marcados para serem visíveis na loja. 
    • Um item inativo no ERP será enviado para o E-commerce como oculto e não ficará visível na loja.
  • A descrição do item no NUVEMSHOP depende do que está configurado na integração E-commerce. Verifique o campo que o sistema leva como descrição do produto e altere se necessário: 

image-1705667608365.png

  • O parâmetro 'Envia descrição (observação) do item' é para enviar o campo 'Observação' do cadastro de itens no ERP/ERPx:

image-1705667757463.png

SINCRONIZAÇÃO NUVEMSHOP 
  • Acesse 'Configurações' e clique em 'Integrar E-commerce'

image-1689354695651.png

Com isso, a sincronização será realizada. E isso já basta para cadastrar no NUVEMSHOP um produto (sendo denominado como "ITEM" no ERP). 

EX: 

  • ERP - Item: 

image-1689354730489.png

Loja do ambiente de teste casadasmaquinas2:  https://www.nuvemshop.com.br/login

Login: desenvolvimento@ema.net.br

Senha: Dev@Ema#2023

  • NUVEMSHOP - Produto: 

image-1689354950506.png

TABELA DE PREÇO 

No NUVEMSHOP existe o campo "Promocional", que difere o valor do campo preço normal

image-1706549615884.png

Para realizar a configuração desse preço promocional é necessário vincular o item do ERP em uma tabela de preço. Acessar: 

  • Vendas 
  • Tabela de preço  

image-1706550025007.png

Ao editar a tabela de preços, na aba 'Itens' é onde vincula o item/produto. O campo promocional é "Valor tabela" 

image-1706550233608.png

Importante ressaltar que, na aba 'Versões', é onde está a data em que este valor promocional é valido. Caso já tenha passado da data, o valor promocional não será enviado. 

* Verificar o campo 'Versão vigente' da tabela de preço. 

Após, realizar a alteração, acesse os parâmetros gerais do e-commerce e vincule a tabela de preço 

image-1706550686863.png

image-1706551031312.png

GRUPOS = CATEGORIA

Agora vamos complementar esse item, incluindo um grupo em seu cadastro. Acesse: 

  • Estoque> 
  • Grupos> 
  • Novo> 

image-1689355469686.png

  • Ao criar um novo, é importante que o parâmetro 'Exporta para NuvemShop' esteja marcado, pois caso não esteja, ao realizar a sincronização, o item será enviado sem grupo. 

image-1690996045905.png

Vincule esse grupo no item escolhido e realize a sincronização novamente. Em seguida verifique no NUVEMSHOP a categoria criada: 

  • ERP - Grupo: 

image-1689355657431.png

  •  NUVEMSHOP - Categoria: 

image-1689355951856.png

  • NUVEMSHOP - Ao editar o produto:

image-1689356007180.png

* Os subgrupos vinculados também serão enviados ao NUVEMSHOP caso o parâmetro esteja marcado. 

CATALOGOS = CATEGORIA 

Assim como na configuração de grupo acima, é possível vincular o item do NUVEMSHOP com uma categoria, esta sendo um CATALOGO DE ITEM no ERP. Para isso, antes precisamos alterar as configurações da integração E-commerce para considerar a exportação de CATALOGO e não GRUPO. 

image-1690997698685.png

Feito, salve e acesse o cadastro de catálogos de itens:

  • Vendas >
  • Catalogo de itens >  

image-1690997192299.png

  • Crie ou edite um catálogo de itens e marque o parâmetro 'Exporta para NuvemShop': 

image-1690997350629.png

  • Em seguida, na aba 'Itens', coloque na grade um item que deseja vincular a este catalogo. 

image-1690997552556.png

Importante: 

  • Não esqueça a configuração de categoria (grupo ou catalogo) nas configurações do E-commerce!
  • Caso o item para exportar esteja vinculado a um catalogo que é FILHO (ou seja, é um catalogo vinculado a outro catalogo pai), o NUVEMSHOP irá realizar a importação de catalogo PAI e FILHO. Esse é um comportamento do E-commerce, mesmo que o catalogo pai não esteja marcado para exportar. 

image-1690999059465.png

  • Após já ter sido enviada a primeira integração dos itens:
    • Se houver necessidade de alterar a configuração do E-commerce em relação ao envio de categoria (grupo ou catalogo), os itens deverão ser vinculados a nova categoria escolhida (grupo ou catalogo).
    • Se já estiverem vinculados ANTES da alteração, deverá ser atualizado o campo "DATAHORAULTIMAATUALIZACAO"  dos itens que são exportados para o NUVEMSHOP.
ITEM COM MARCAS 

Para o envio de marcas vinculados ao item no NUVEMSHOP, acessar:

  • Estoque > 
  • Marcas > 

image-1705668293305.png

  • Deve estar marcado o parâmetro 'Exporta para Nuvemshop' para sincronizar para o e-commerce.
  • Em seguida, editar o item e vincular a marca na aba 'Adicionais' > 'Informações gerais'

image-1705668429049.png

  • Realize a sincronização conforme passado anteriormente. 
  • Verifique no NUVEMSHOP a marca vinculada no item em 'Tags e SEO' 

image-1705668574498.png

ITEM = ABA 'INTEGRAÇÕES'
  • Editar o item > 
  • Acessar a aba 'Integrações' 
  • Preencher os campos disponíveis: 
    • Campo 'Título SEO'. 
    • Campo 'Descrição SEO'.
    • Campo 'Tags'
    • Campo 'Link vídeo'.
    • Campo 'Comprimento'.
    • Campo 'Largura'.
    • Campo 'Altura'.
    • Campo 'Área m2': Este campo é somente leitura e faz um calculo baseado no comprimento, largura e altura informados.
    • Parâmetro 'Frete grátis'

image-1710953939064.png

  • Realize a sincronização conforme passado anteriormente. 
  • Verifique no NUVEMSHOP o item sincronizado.
  • O campo 'Link video' disponível mais acima.
  • E os demais campos estarão disponíveis em 'Tags e SEO'.

image-1705669086738.png

  • O parâmetro 'Frete grátis' mais abaixo conforme imagem.

Importante!

  • A aba 'Integrações' só ficará disponível no cadastro do cliente caso a integração e-commerce do sistema for do tipo 'NuvemShop'.
  • Caso o item que você esteja editando e colocando as informações na aba 'Integrações' fazer parte de um agrupamento, todos os outros itens agrupados juntos terão as informações dessa aba replicadas. Altere em um item, e todos os outros serão atualizados. Caso o item seja simples sem nenhum agrupamento, as informações serão enviadas individualmente.
SINCRONIZAÇÃO ESTOQUE

Após realizar a inclusão do item no ERP e sincronizar para o NUVEMSHOP, precisamos atualizar o estoque do item. Acesse: 

  • Estoque> 
  • "Ajustar estoque"> 

image-1689623629408.png

  • Vincule o item que foi sincronizado mais cedo e mude seu saldo. 

image-1689623962484.png

  • Realize a sincronização conforme passado anteriormente. 
  • Verifique no NUVEMSHOP o novo saldo de estoque deste item. 

image-1689624205256.png

Importante!

Outras informações como preço, descrição, observação são atualizadas ao editar no ERP e sincronizar novamente. Abaixo algumas regras implementadas na integração em relação ao estoque do item:

  • O NUVEMSHOP não aceita envio de estoque negativo, então se o estoque atual do item no ERP for negativo, será enviado estoque zero para o E-commerce.
  • Integração de estoque atual após ajuste manual de estoque (conforme mostrado acima) ou nota fiscal de entrada, respeitando o parâmetro de estoque reservado das configurações de E-commerce, se estiver marcado, envia o estoque considerando os reservados. 

image-1705667869520.png

AGRUPAMENTO = VARIAÇÕES 

Vamos vincular um item em um agrupador no ERP e configurar sua grade/tamanho/cor. Porém, antes de iniciar, vamos verificar alguns parâmetro da integração E-commerce NUVEMSHOP: 

  • Exporta itens agrupados e suas variações (cor e tamanho): Esse parâmetro tem que estar marcado para que o agrupamento seja enviado para o NUVEMSHOP. 

    image-1705667902685.png

    importante!

    Abaixo algumas regras implementadas na integração em relação a este parâmetro: 

    • Se configuração NÂO está marcada para exportar item agrupado:
      • Serão enviados os itens marcados para exportar para terceiros de forma individual, sem considerar agrupamento;
    • Se configuração ESTÁ marcada para exportar item agrupado:
      • Serão enviados os itens vinculados a agrupamento que exporta para terceiros e que tenham variação (grade, tamanho e cor). Mesmo que o item em si não esteja marcado para exportar, caso o agrupamento esteja, o item será enviado; 
        • Serão enviados os itens marcados para exportar para terceiros e sem agrupamento;
    • NÃO envia item com agrupamento que não tenha grade, tamanho e cor, será apontado um erro no log "Produto agrupado sem variação".

    Agora vamos configurar o agrupamento para enviar. Acesse: 

    • Estoque> 
    • Agrupamentos> 
    • Novo> 

    image-1689599944728.png

    • Ao criar um novo, é importante que o parâmetro 'Exporta para NuvemShop' esteja marcado, pois caso não esteja, ao realizar a sincronização, o agrupador será desconsiderado. 

    image-1690995788978.png

    Após isso, precisamos configurar a grade + tamanho + cores do agrupamento. Acesse: 

    • Estoque> 
    • Grade de itens > 
      • Grades 
      • Grade - Tamanhos 
      • Grade - Cores

    image-1689600748246.png

    • No cadastro 'grades ' vincule os tamanhos/cores cadastrados.  Agora, selecione os ITENS que deseja incluir nesse agrupamento, edite e informe a grade, tamanho, e cor. 

    image-1689602132050.png

    • Neste exemplo, fizemos isso com três itens, todos com tamanho/cor diferentes. 

    image-1689602221601.png

    • Feito a configuração no ERP, realize a sincronização e verifique no NUVEMSHOP o produto cadastrado. 

    image-1689602610887.png

    Importante!

    O que acontece aqui é que o item enviado para o NS com um agrupamento é incluído como uma VARIAÇÃO. E o agrupamento em si é incluído como um produto.  

    • Clique sobre o produto. ("Tênis" nesse exemplo).
    • Em 'Variações' ao clicar sobre cada um, é aberto ao lado a tela para mostrar as informações dessa variação como ITEM (tal como descrição, preços, SKU, código de barras, peso e dimensões, etc).
    • * Ao deletar o item (agrupamento) no NUVEMSHOP, as variações são deletadas também.

    image-1689622198596.png

    SINCRONIZAÇÃO CLIENTE

    Existe apenas uma forma de incluir um novo cliente no ERP pelo NUVEMSHOP, que seria ao incluir um pedido, colocando as informações do cliente (Nome, Sobrenome, E-mail, Telefone e CPF/CNPJ).  

    image-1698684469480.png

    Importante!

    Abaixo algumas regras implementadas na integração do NUVEMSHOP para cadastro de CLIENTE: 

    • Ao realizar a sincronização, será verificado se o CNPJ/CPF informado existe no ERP.
      • Caso o CNPJ/CPF não exista, será verificado o E-mail. 
      • Caso o E-mail não exista, será verificado o telefone.  
      • Se não existir nenhuma dessas informações, será criado um novo usuário no ERP. 
    • Caso a CIDADE não seja informada na criação do pedido, ao sincronizar, o sistema irá incluir e vincular o campo CIDADE do cliforemp como ZERO. A edição/manutenção deste campo fica por parte do usuário do ERP. 
    • Ao importar as cidades dos clientes do E-commerce é considerado acentos e cedilhas. Assim como nas demais integrações no ERP, seguirá o padrão:
      • Se encontrar a cidade, vincula a cidade encontrada no cliente.
      • Se não encontrar a cidade, cria uma nova cidade, porém, sem IBGE, pois o NUVEMSHOP não tem código IBGE para vincular.

    Coloque as informações do cliente e acesse o ERP para realizar a sincronização.

    SINCRONIZAÇÃO PEDIDOS 

    Antes de tudo, acesse a configuração do E-commerce e vamos verificar algumas informações dos pedidos. 

    • Vendas >
    • Vendas móveis > Parâmetros > Integração E-commerce >
    • Editar a integração do tipo 'NuvemShop' >
    • Aba 'Pedido' >
    • Campos 'Condição' e 'Método' > 

    image-1705667983646.png

    Os pedidos importados do E-commerce devem seguir o padrão de método/condição configurados nesses dois campos. Agora, vamos criar um pedido no NUVEMSHOP e sincronizar para o nosso ERP.

    • Acesse a aba "Lista de vendas" conforme imagem abaixo. 
    • "Criar novo pedido".  

    image-1689622679255.png

    • Informar produtos, cliente, e outras informações e salvar. 
    • Em seguida acessar ERP e realizar a sincronização do E-commerce. 
    • Acessar Vendas > Pedidos
    • Procurar o pedido criado e verificar as informações inseridas. 

    Ex: 

    Pedido - NUVEMSHOP

    image-1691000352050.png

    Pedido - ERP 

    image-1691000408660.png

    Importante!

    Abaixo algumas regras implementadas na integração do NUVEMSHOP para cadastro de PEDIDO:

    • Importa somente pedidos com status "paid" (pagamento confirmado). 
    • Importa observação do pedido da loja para o campo 'Observação' do pedido no ERP. 
    • Ao criar um pedido no NUVEMSHOP, vincular um item e sincronizar, esse item precisa existir no ERP (SKU), ou o log apontará erros e não será sincronizado. 
    • Na tabela PALMTOP_PEDIDO foi adicionado o campo "NUMERO" do tipo VARCHAR (30);
    • Na integração com o NuvemShop, ao buscar o pedido para inserir no ERP, irá pegar o conteúdo da tag "number" e inserir neste novo campo e posteriormente este campo será levado para o campo NUMERO da tabela PEDIDO.
    • Nas demais integrações, não foi mexido em nada, então ao gerar o pedido, o campo NUMERO irá ficar igual ao IDPEDIDOPDA, como já era.
    DE/PARA NA INTEGRAÇÃO DE PEDIDOS

    Assim como informado acima, ao realizar a importação de um pedido do NUVEMSHOP, o sistema irá vincular o método e condição de pagamento automaticamente com o que está configurado na integração E-commerce.

    Porém, existe um parâmetro permite com que o sistema traga diferentes métodos e condições de acordo com a forma de pagamento escolhida no site NUVEMSHOP. 

    • Acessando as configurações do E-commerce, aba 'Pedido' marque o parâmetro 'Informa métodos e condições específicos para cada forma de pagamento". 

    image-1705668014705.png

    Em seguida, na aba 'Métodos', informe os métodos escolhidos para cada forma de pagamento no NUVEMSHOP. No exemplo abaixo, criamos uma forma de pagamento PERSONALIZADA (PIX) no site e o retorno dessa personalização é descrito como "custom". 

    image-1691002551568.png

    • Forma E-commerce: custom
    • Método - Descrição: 6 - Boleto 
    • Parcela: 1 
    • Condição - Descrição: 1 - Em espécie

    Com isso, todo pedido criado no NUVEMSHOP que possua o método de pagamento PIX (custom) será importado no ERP com o método 'Boleto' e a condição 'Em espécie (dinheiro)'. 

    Importante! 

    • Campo "Parcela" deve receber 1 de valor mínimo e máximo, pois atualmente não está implementado na integração ERP x NuvemShop mais de 1 parcela.
    • Caso o parâmetro "Informa métodos e condições especificas para cada forma de pagamento" esteja marcado, mas nada esteja informado na aba 'Métodos', considera o método/condição informados na aba 'Pedido'.
    • Caso o campo "Forma E-commerce" esteja com descrição 'null', sistema considera o método/condição informados na aba 'Pedido'. 
    • Campo 'Forma E-commerce' é case sensitive, então deve-se colocar em minúsculo/maiúsculo exatamente como informado no NUVEMSHOP.
    • No exemplo que criamos, o retorno do método personalizado no NUVEMSHOP foi "custom" pois foi em ambiente de teste e tínhamos acesso as informações. Porém, ao implementar a integração DE/PARA em cliente, deve-se consultar o suporte do NUVEMSHOP e solicitar a descrição retornada dos métodos desejados. 
    TABELAS E LOG E-COMMERCE 

    Tabelas relacionadas à integração E-commerce (NÃO TODAS). Utilizamos os comando abaixo para "zerar" a base de teste e podermos começar a exportar novos registros sem dar nenhum conflito com sincronizações anteriores.

    ** IMPORTANTE realizar em uma base de teste e verificar se necessário adicionar a clausula WHERE, para não afetar registros importantes. 

    • Grupo: 
    DELETE 
  FROM INTEGRACAOECOMMERCE_GRUPO
    UPDATE GRUPO 
   SET EXPORTAWEB = 'N'
    • Item: 
    DELETE 
  FROM INTEGRACAOECOMMERCE_ITEM
    UPDATE ITEM 
   SET EXPORTAPALM = 'N'

    Sobre os logs do E-commerce, toda vez que algum problema surge durante a sincronização o sistema guarda o retorno para consulta. Acesse: 

    • Configuração> 
    • Logs de integração E-commerce

    image-1689626716731.png

    Importante que sempre depois de uma integração bem sucedida, ter o costume de verificar o log para garantir que pequenos detalhes não passem despercebidos. Assim como foi descrito ao longo deste conteúdo, algumas mensagens de erro são auto entendíveis ou de fácil solução para o usuário: 

    • Não envia item com agrupamento que não tenha grade, tamanho e cor (erro log "Produto agrupado sem variação.")

    Porém ainda existem outras mensagens mais técnicas que são mostradas em log e dependendo do contexto, são importantes serem verificadas. 

    É necessário ABRIR TAREFAS sobre melhorias no log, caso necessário. 

    TESTE / QA 

    Para realizar os testes dessa integração com possíveis melhorias e correções, leia o conteúdo desde o começo e acesse o ambiente demo (para testes): 

    Tudo o que for feito no ERP (conforme os exemplos acima) e depois sincronizado, aparecerá nesse ambiente demo (devidamente configurado nessa loja). 

    Importante ressaltar que a Ema é parceira do NUVEMSHOP, então a conta disponibilizada é uma conta DEMO para testes. Mesmo que apareçam avisos de plano ou encerramento de teste grátis, a conta possui todas as funções necessárias para os testes com o ERP. Se houver duvidas, contatar o suporte do NUVEMSHOP e informar o e-mail, passando as duvidas em seguida. 

    • Para realizar um pedido pela loja propriamente dita do ambiente demo, acesse "Meus aplicativos" e clique no ambiente de teste atual 'Demo casa das Maquinas'.  

    image-1691003139898.png

    • Será redirecionado para o site E-commerce, contendo os produtos para compra. 

    image-1691003232568.png

    • Após realizar alguma compra e verificar na lista de pedidos por exemplo, aparecerá as informações incluídas. Ao sincronizar, também aparecerá no ERP.  

    image-1691003337222.png

     

    Voltar ao topo