Integração Nuvemshop
Loja Nuvemshop com o ERP TNK
O integrador da TNK publica os produtos do ERP na loja e traz os pedidos de volta. Ele governa parte do catálogo sozinho — e essa é a parte que, mexida à mão, volta atrás na próxima sincronização sem gerar erro nenhum. Documento voltado a quem desenvolve a loja.
Esta é a versão sempre atual. Ela vive em docs.tnksystem.com.br/nuvemshop e é atualizada quando a integração muda. Se algo que você leu em outro lugar divergir daqui, o que vale é esta página.
1Quem faz o quê
O integrador é um aplicativo que roda na máquina do lojista, atrás do firewall dele, e conversa com a API da Nuvemshop usando o token da própria loja. Não existe servidor da TNK no meio, e você não precisa de credencial nenhuma da TNK para trabalhar.
| Assunto | Quem manda |
|---|---|
| Catálogo: produto, preço, estoque, categoria | O ERP, pelo integrador |
| Tema, layout, páginas institucionais | Você |
| Pedidos | Nascem na loja, o integrador grava no ERP |
| Conexão da loja (OAuth) | O lojista, um clique no app da TNK |
A regra que resolve quase toda dúvida: o ERP é a fonte da verdade do catálogo. A loja é vitrine. O que o lojista quiser mudar num produto, ele muda no ERP.
2O que o integrador governa
A cada sincronização o integrador atualiza o produto na loja e escreve estes campos com o valor que está no ERP. Não há mesclagem: o valor do ERP substitui o que estiver lá.
| Nível | Campos sobrescritos |
|---|---|
| Produto | name, handle, description, published,
categories, metadata — e seo_title,
seo_description, brand quando o ERP tem esses dados |
| Variante | price, promotional_price, stock, sku,
e as medidas físicas weight, height, width,
depth |
| Categorias | Criadas e atualizadas a partir do cadastro do ERP |
Editar um desses campos pelo painel da Nuvemshop funciona: você salva, a loja mostra o valor novo, ninguém reclama. Na sincronização seguinte o integrador reescreve com o valor do ERP e sua alteração desaparece — sem mensagem, sem erro do seu lado.
O sintoma que chega ao suporte é sempre o mesmo: alguém corrigiu uma descrição na loja, viu voltar ao texto antigo horas depois e concluiu que "a loja está desfazendo sozinha". Não está: está sendo sincronizada. A correção tem que ser feita no ERP.
A promoção também é campo do ERP. Uma campanha montada direto na Nuvemshop dura até a próxima rodada de sincronização — que pode ser em minutos. Promoção precisa sair do ERP, senão ela cai no meio da campanha.
3O que é seu
Fora a lista acima, a loja é sua. O integrador não toca em:
- tema, template, CSS e JavaScript da vitrine;
- páginas institucionais, banners, menus e conteúdo editorial;
- configurações de frete, meios de pagamento e checkout;
- cupons, descontos de carrinho e regras promocionais da própria plataforma;
- aplicativos de terceiros instalados na loja;
- imagens que você adicionar além das que vieram do ERP.
4O vínculo, e como ele quebra
Cada produto do ERP guarda o id do produto correspondente na Nuvemshop. É esse vínculo que faz a segunda sincronização virar uma atualização em vez de criar um produto duplicado, e é ele que permite ao pedido voltar sabendo qual item do ERP foi vendido.
Apagar um produto na loja e criar outro no lugar — ainda que idêntico — gera um id novo. O vínculo antigo passa a apontar para um produto que não existe mais, e o integrador trata o item como não vinculado.
Isso vale principalmente para "limpezas" em massa do catálogo antes de publicar a loja. Se precisar zerar o catálogo, avise o suporte antes: existe procedimento para reconstruir os vínculos, e refazer à mão custa caro.
Produtos criados por você direto na loja não têm vínculo com o ERP. Eles aparecem na vitrine, mas não recebem preço nem estoque do ERP — e, se forem vendidos, travam a importação do pedido inteiro.
5Pedidos voltando para o ERP
O pedido nasce na loja. O integrador recebe o aviso, busca o pedido completo na API e grava no ERP, baixando o estoque dos itens vendidos.
Se qualquer item do pedido não estiver vinculado a um produto do ERP, a importação falha antes de gravar qualquer coisa — de propósito. É melhor o pedido ficar pendente e visível do que entrar pela metade e sujar o estoque.
Consequência prática: um produto que você criou à mão na loja, se for vendido, segura aquele pedido até alguém resolver o vínculo.
Reenvio do mesmo pedido é seguro: o integrador guarda uma impressão digital do conteúdo e ignora a reimportação idêntica, para não baixar estoque duas vezes. Se o mesmo pedido voltar com conteúdo diferente, a importação automática é bloqueada e registrada — alguém precisa olhar antes.
6Antes de publicar a loja
- O lojista já conectou a loja pelo app da TNK (aba Conexão) e o Testar Conexão mostra a loja certa.
- As categorias foram sincronizadas antes dos produtos.
- Os produtos da vitrine vieram do ERP — nenhum foi criado à mão no painel.
- Você não editou nome, descrição, preço, estoque, SKU ou categoria pelo painel da Nuvemshop.
- Um pedido de teste foi feito na loja e apareceu no ERP.
- Se em algum momento você precisou apagar produtos, o suporte foi avisado.