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:

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.

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

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

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

🛠️ 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.