Description

n8n-nodes-nuvemshop

Node comunitário do n8n para integrar Nuvemshop e Tiendanube. Inclui um node de ações com campos guiados, uso como Tool de Agente de IA e um Trigger real para webhooks da API oficial.

Funcionalidades

✨ Funcionalidades

📦 Instalação

Pela interface do n8n

1. Abra Settings → Community Nodes.
2. Clique em Install a community node.
3. Informe n8n-nodes-nuvemshop.
4. Confirme a instalação e reinicie o n8n quando solicitado.

Instalação npm self-hosted

cd ~/.n8n
npm install n8n-nodes-nuvemshop

Reinicie o processo ou container do n8n após instalar.

🔐 Credenciais

Crie uma credencial Nuvem Shop API e escolha o tipo conforme o fluxo:

| Tipo | Quando usar |
| ———————————— | ————————————————————————————– |
| Store API | Produtos, pedidos, clientes e demais operações de uma loja já autorizada |
| App OAuth and Partner Actions | Trocar o authorization code ou executar Partner Actions antes de existir token da loja |
| Store and App (Full Integration) | Store API, Partner Actions e Trigger com HMAC na mesma integração |

Configuração passo a passo

1. No Portal de Parceiros da Nuvemshop, crie ou abra seu aplicativo.
2. Configure uma URL de redirecionamento HTTPS para receber o code do OAuth.
3. Copie App ID e Client Secret para uma credencial do tipo App ou Full Integration.
4. Envie o lojista para a URL de autorização do aplicativo.
5. Capture o code retornado. Ele expira em cinco minutos.
6. No node, use Authorization → Exchange Authorization Code.
7. Copie accesstoken e userid da resposta.
8. Salve accesstoken como Access Token e userid como Store ID.
9. Escolha a região correta e mantenha 2025-03 para operações atuais.
10. Informe um User-Agent com nome e URL de contato do aplicativo.
11. Teste a credencial no editor do n8n.

| Campo | Obrigatório | Como preencher |
| ————— | ———– | —————————————————————— |
| Credential Type | Sim | Store, App ou Full Integration |
| Access Token | Store/Full | Token OAuth permanente da loja |
| Store ID | Store/Full | Valor user_id retornado pelo OAuth |
| Region | Sim | Brazil para Nuvemshop; International para Tiendanube |
| API Version | Sim | 2025-03 recomendado; v1 ou unstable quando a operação exigir |
| User Agent | Sim | Nome do app e e-mail ou URL pública de contato |
| App ID | App/Full | ID do aplicativo no Portal de Parceiros |
| Client Secret | App/Full | Segredo OAuth, Partner Actions e assinatura do Trigger |

Solicite apenas os escopos usados pelo workflow. Tokens, IDs da loja e segredos ficam na credencial criptografada e nunca devem ser colocados em Body, Query ou $fromAI().

🧩 Nós e Operações

O pacote instala:

Cobertura de recursos

| Domínio | Recursos e operações |
| ———- | —————————————————————————————– |
| Catálogo | Category, Product, Product Variant, Product Image, Price Table, custom fields e Metafield |
| Comércio | Customer, Coupon, Cart, Abandoned Checkout, Order e Draft Order |
| Pagamentos | Transaction, Dispute, Payment Option, Payment Provider e Billing |
| Logística | Location, Fulfillment Order, Fulfillment Event, Shipping Carrier e opções |
| Conteúdo | Blog, Page, Email Template e Script |
| Plataforma | Store, Webhook, Discount, Business Rule, Kit e Authorization |
| Avançado | Custom API Call com GET, POST, PUT, PATCH, DELETE e HEAD |

Cada recurso mostra somente operações compatíveis. Operações de leitura são o default sempre que existem. Use Get Many para localizar IDs antes de Update/Delete; não invente ou reutilize IDs de outro tipo de recurso.

Price Table (tabelas de preço B2B)

O recurso Price Table gerencia as tabelas de preço da API 2025-03: um desconto padrão para a loja inteira, exceções por categoria e exceções por variante (com preço fixo opcional) e os clientes que usam a tabela. A regra mais específica vence: variante, depois categoria, depois o desconto padrão.

| Operação | Rota |
| —————————— | —————————————————————– |
| Create | POST /products/price-tables |
| Get | GET /products/price-tables/{id} |
| Get Many | GET /products/price-tables |
| Update | PUT /products/price-tables/{id} |
| Set Categories | PUT /products/price-tables/{id}/categories |
| Get Category | GET /products/price-tables/{id}/categories/{categoryId} |
| Get Categories | GET /products/price-tables/{id}/categories |
| Delete Category | DELETE /products/price-tables/{id}/categories/{categoryId} |
| Set Variants | PUT /products/price-tables/{id}/product-variants |
| Get Variant | GET /products/price-tables/{id}/product-variants/{variantId} |
| Get Variants | GET /products/price-tables/{id}/product-variants |
| Delete Variant | DELETE /products/price-tables/{id}/product-variants/{variantId} |
| Add Customers | PUT /products/price-tables/{id}/customers |
| Approve Customers | POST /products/price-tables/{id}/approve-customers |
| Get Customers | GET /products/price-tables/{id}/customers |
| Delete Customer | DELETE /products/price-tables/{id}/customers/{customerId} |
| Get Price Tables of a Customer | GET /products/price-tables/customers/{customerId} |

Na versão 2 do node, a tabela e o cliente são lista pesquisável com a opção de colar o ID. A API devolve no máximo 10 itens por página nas tabelas e 50 nas sublistas; Return All respeita esses limites. Um cliente só pode estar em uma tabela: se algum cliente do lote já tem tabela, Add Customers falha inteiro com 409 e a resposta lista os clientes em conflito. Para mudar um cliente de tabela, use antes Delete Customer.

#### Exemplo: criar uma tabela e ligar clientes

1. Em Price Table → Create, preencha Name (por exemplo Atacado) e Default Discount (por exemplo 7.00).
2. Em Price Table → Set Categories, escolha a tabela e envie [{"id":"1238746858","discount":"20.00"}].
3. Em Price Table → Add Customers, escolha a tabela e envie ["123456789","654987321"].

Remoções em massa com confirmação

Duas operações apagam vários itens de uma vez e por isso trazem um interruptor desligado por padrão. Sem ele ligado, a operação falha antes de qualquer requisição.

| Operação | Rota | Interruptor |
| ———————————- | ——————————————————— | ——————————- |
| Discount → Delete All Promotions | DELETE /promotions (todas as promoções do app) | Confirm Delete All Promotions |
| Business Rule → Delete Integration | DELETE /business_rules/integrations/{domain}?events=... | Confirm Delete Integration |

Em Delete Integration, informe events em Filters (por exemplo payments/before-filter, separados por vírgula) ou all para apagar todos os callbacks do app.

📝 Preenchimento guiado

Operações com Body ou filtros apresentam três níveis:

1. Campos obrigatórios — aparecem diretamente e precisam ser preenchidos.
2. Additional Fields / Update Fields / Filters — clique em Add Field e escolha somente os dados necessários.
3. Advanced Body (JSON) / Additional Query Parameters (JSON) — fallback opcional para campos raros ou recém-publicados pela API.

Campos guiados são convertidos automaticamente para os nomes snake_case exigidos pela API. Quando o mesmo campo existir no JSON avançado e na interface guiada, o valor guiado vence.

Valores multilíngues simples usam o idioma escolhido em Content Language (pt, ptBR, es, esAR ou en). Para enviar vários idiomas no mesmo campo, use o JSON avançado:

{
	"name": {
		"pt": "Camiseta",
		"es": "Remera",
		"en": "T-Shirt"
	}
}

Arrays simples, como IDs de categorias, podem ser informados separados por vírgula. Objetos complexos, variantes, imagens e produtos de um pedido usam um campo JSON dedicado com exemplo visível.

Node versão 2: listas e datas

Em node novo (versão 2), o node mostra no editor:

Workflows salvos continuam na versão 1, com os mesmos campos de antes. Local, variante e webhook seguem como dropdown nas duas versões.

🚀 Exemplos

Criar um produto

1. Selecione Product → Create.
2. Preencha Name.
3. Em Additional Fields, adicione Published, Brand, Categories, Variants ou Images.
4. Use Category → Get Many para obter IDs de categorias.
5. Execute e guarde o ID do produto retornado.

Exemplo do campo Variants:

[
	{
		"values": [{ "pt": "M" }],
		"price": "79.90",
		"stock_management": true,
		"stock": 25,
		"sku": "CAM-M"
	}
]

Criar e confirmar um pedido rascunho

1. Use Product → Get by SKU ou Get Many para localizar a variante.
2. Use Draft Order → Create e preencha contato, pagamento e Products.
3. Revise totais e itens com Draft Order → Get.
4. Confirme somente após revisão humana com Draft Order → Confirm.

Atualizar pedido com segurança

1. Use Order → Get Many com filtros de status/data.
2. Escolha o pedido pelo dropdown ou passe o ID retornado por expressão.
3. Consulte Order → Get antes da alteração.
4. Use Update, Cancel, Close ou Edit somente com validação do estado atual.

🤖 Usar como Tool de Agente de IA

O node de ações define usableAsTool: true. Não existe um node Tool separado.

Habilitar community nodes como tools

Em instalações self-hosted, defina:

N8NCOMMUNITYPACKAGESALLOWTOOL_USAGE=true

| Instalação | Onde definir |
| ———————– | ——————————————————— |
| Docker / docker-compose | Em environment: ou no .env; depois recrie o container |
| npm / npx | Exporte a variável antes de executar n8n start |
| n8n Cloud | Disponível nos planos que suportam community nodes |

Sem essa variável, o Nuvem Shop pode não aparecer no conector Tool do AI Agent.

Operações novas para agentes: Price Table (as 17 operações; use as de leitura com $fromAI() apenas para filtros), Delete All Promotions e Delete Integration. As duas remoções só rodam com o interruptor de confirmação ligado; deixe-o fixo e desligado, e ligue-o só após revisão humana.

Configuração recomendada

1. Adicione um AI Agent e conecte um Chat Model.
2. No conector Tool, adicione Nuvem Shop.
3. Escolha um único Resource e Operation por node.
4. Dê um nome estreito, como NuvemShopGetProduct.
5. Fixe campos de segurança e deixe para a IA apenas parâmetros operacionais.

Use o botão Let the model define this ou uma expressão $fromAI():

{{ $fromAI('sku', 'SKU exato da variante, por exemplo CAM-M', 'string') }}

Assinatura: $fromAI(key, description?, type?, defaultValue?). Tipos aceitos: string, number, boolean e json.

Boas práticas:

🪝 Trigger (Webhook)

O Nuvem Shop Trigger registra webhooks ao ativar o workflow e remove os registros ao desativá-lo.

1. Crie uma credencial Full Integration com Client Secret.
2. Adicione o Trigger e selecione os eventos.
3. Ative Verify HMAC Signature.
4. Use uma URL de produção HTTPS; localhost não é aceito.
5. Ative o workflow para registrar os webhooks.

Famílias suportadas: app, app subscription, category, charge, checkout, coupon, customer, order, product, product variant, custom field, domain, theme, navigation, subscription, fulfillment, fulfillment order, label, tracking event e location. Os eventos charge/* e app_subscription/updated só chegam a apps com cobrança (billing).

Eventos de privacidade são configurados no Portal de Parceiros:

Copie a Production URL do Trigger para o evento correspondente. A assinatura usa o header x-linkedstore-hmac-sha256 e o Client Secret. Eventos podem chegar repetidos ou fora de ordem; faça workflows idempotentes.

📚 Paginação e limites

🔧 Custom API Call

Use quando a Nuvemshop publicar uma rota antes da atualização deste pacote ou quando uma API restrita for liberada para seu aplicativo.

🧯 Solução de problemas

| Sintoma | Verificação |
| ———————————- | ————————————————————————- |
| Node não aparece como Tool | Configure N8NCOMMUNITYPACKAGESALLOWTOOL_USAGE=true e reinicie o n8n |
| 401 Unauthorized | Confira Access Token, região e tipo da credencial |
| 403 Forbidden | Confirme os escopos concedidos ao aplicativo |
| 400 Bad Request | Revise campos obrigatórios, User-Agent e formato do Body |
| 404 Not Found | Confira Store ID, versão da API e ID do recurso |
| 429 Too Many Requests | Aguarde o retry e reduza concorrência/paginação |
| Dropdown vazio | Preencha primeiro o recurso pai ou use uma expressão com ID confiável |
| Trigger não ativa | Use URL HTTPS pública e credencial Full Integration |
| Assinatura HMAC falha | Confira Client Secret e se o proxy preserva body/header originais |
| Evento de privacidade não registra | Configure o evento diretamente no Portal de Parceiros |

🛠️ Desenvolvimento

Requer Node.js 24 para o toolchain do repositório.

npm ci
npm run lint
npm test
npm run build
npm pack --dry-run

Use npm run dev para carregar o node em uma instância local do n8n.

✅ Compatibilidade

📚 Recursos

🚀 Publicação

A tag vX.Y.Z (ou o workflow_dispatch) dispara o workflow publish.yml, que roda lint, testes e build e envia a versão com npx -y [email protected] stage publish --provenance --access public. A versão fica em espera: ela só vai ao ar depois que o dono a aprova, com 2FA, na aba Staged Packages do npmjs.com. Sem a aprovação, nada muda no registro.

📈 Versões

Consulte o CHANGELOG para detalhes técnicos.

🆘 Suporte

1. Confira credencial, região, API Version e escopos.
2. Execute a operação Get antes de mutações para validar IDs e estado.
3. Consulte os logs do n8n e a mensagem retornada pela API.
4. Abra uma issue no GitHub com versão do n8n, operação e erro sem incluir tokens.

☕ Apoie o projeto

Este node é mantido de forma independente. Se ele ajuda suas automações, você pode apoiar o desenvolvimento, a manutenção e as novas integrações pelo Buy Me a Coffee.

📄 Licença

MIT

Nuvemshop e sua marca pertencem aos respectivos titulares. Este pacote comunitário não é um produto oficial da Nuvemshop.