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.

🧭 Navegação

• Funcionalidades
• Instalação
• Credenciais
• Nós e operações
• Preenchimento guiado
• Exemplos
• Tool de IA
• Webhook Trigger
• Paginação e limites
• Custom API Call
• Solução de problemas
• Desenvolvimento
• Compatibilidade
• Recursos
• Versões
• Suporte
• Licença

✨ Funcionalidades

• 198 operações explícitas organizadas em 36 recursos.
• Campos guiados e tipados para payloads e filtros comuns.
• Campos obrigatórios visíveis nas operações principais.
• JSON avançado opcional para contratos completos e recursos novos.
• Dropdowns dinâmicos para produtos, variantes, categorias, clientes, cupons, pedidos, locais e webhooks.
• Defaults seguros: operações de leitura são selecionadas antes de mutações.
• API estável 2025-03, rotas legadas v1 e operações unstable documentadas.
• Regiões Brasil/Nuvemshop e internacional/Tiendanube.
• OAuth, Store API, Partner Actions, paginação, multipart e respostas binárias.
• Compatibilidade com AI Agent por usableAsTool: true.
• Registro e remoção automática de webhooks com validação HMAC SHA-256.
• Sem dependências de runtime.

📦 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 access_token e user_id da resposta.
8. Salve access_token como Access Token e user_id 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:

• Nuvem Shop — ações da API, paginação, upload e uso como Tool.
• Nuvem Shop Trigger — recebimento de eventos via webhook.

Cobertura de recursos

| Domínio | Recursos e operações | | ---------- | ---------------------------------------------------------------------------- | | Catálogo | Category, Product, Product Variant, Product Image, 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.

📝 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, pt_BR, es, es_AR 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.

🚀 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.

🤖 Tool 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:

N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_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.

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 NuvemShop_Get_Product.
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:

• Exponha somente operações necessárias ao agente.
• Use credencial dedicada com menor privilégio.
• Nunca permita que o modelo invente IDs.
• Este node não impõe aprovação automaticamente. Adicione uma etapa externa de revisão humana antes de Delete, Cancel, pagamentos, disputas, estoque, preço, fulfillment e publicação.
• O Nuvem Shop Trigger não é uma Tool; triggers não podem ser conectados ao AI Agent.

🪝 Webhook Trigger

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, category, customer, order, product, product variant, custom field, domain, subscription, fulfillment, fulfillment order, label, tracking event e location.

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

• store/redact
• customers/redact
• customers/data_request

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

• Return All percorre as páginas automaticamente.
• Limit restringe o total de itens retornados.
• O node usa páginas de até 200 itens e intervalo de 500 ms.
• Consultas de pedidos podem ser limitadas a 10.000 resultados; use datas incrementais.
• Para 429, respeite o tempo de retry e evite repetir escritas não idempotentes.

🔧 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.

• Endpoint sempre relativo, por exemplo /products.
• Domínios externos, traversal, barras invertidas e caracteres de controle são bloqueados.
• Store scope usa Store ID e Access Token.
• Partner App scope usa App ID e Client Secret.
• Suporta JSON, multipart e arquivo binário.

🧯 Solução de problemas

| Sintoma | Verificação | | ---------------------------------- | ------------------------------------------------------------------------- | | Node não aparece como Tool | Configure N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_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

• n8nNodesApiVersion 1.
• Node.js 24 no desenvolvimento e publicação.
• API 2025-03 como padrão.
• Rotas v1 e unstable selecionadas por operação quando necessário.
• Nuvemshop Brasil e Tiendanube internacional.

📚 Recursos

• Nuvemshop API — introdução
• Autenticação
• Partner Actions
• Webhooks
• Community nodes do n8n
• Tools Agent
• $fromAI()

📈 Versões

• 1.1.0 — campos guiados, filtros, dropdowns ampliados, defaults seguros e documentação pt-BR otimizada para AI Tools.
• 1.0.0 — primeira versão pública com 198 operações, paginação, Partner Actions, Custom API Call e Trigger HMAC.

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.

📄 Licença

MIT

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