O que o Code Faz
O nó Code no n8n é sua ferramenta principal para manipular, transformar e estruturar dados usando JavaScript customizado, oferecendo uma solução mais rápida, previsível e rigidamente controlada do que nós baseados em IA ou pré-construídos para operações complexas.
- Executa JavaScript customizado em dados JSON recebidos, seja em cada item individualmente ou em todo o lote de uma vez
- Permite remodelar saídas, adicionar novos campos, realizar cálculos, filtrar resultados ou reestruturar completamente seus dados para atender requisitos de nós downstream
- Essencial para tarefas onde nós integrados ou expressões não são suficientes, como matemática avançada, remodelagem única de JSON ou lidar com peculiaridades de resposta de API
Principais Casos de Uso
- Transformação de formato: Converter respostas de API (achatar objetos, dividir strings, agrupar campos)
- Cálculos customizados: Agregar somas, porcentagens ou criar novos campos computados
- Manipulação de conteúdo: Extrair partes de uma string, limpar texto, analisar datas, reformatar emails
- Filtragem de dados: Manter apenas itens que correspondem a regras complexas de múltiplas condições
- Preparar payloads para APIs, bancos de dados ou ferramentas de mensagens que precisam de estrutura precisa
Como Usar Efetivamente
- Entender Dados Recebidos: Sempre inspecione o JSON recebido para ver o que seu código receberá. Use o painel "Execution Data" ou console.log (para configurações self-hosted) para debug
- Escrever Código Focado: A maioria do código funciona na variável
item.json, representando um item de workflow de cada vez. Você pode fazer loop por todos os itens ou processar cada um individualmente dependendo de suas necessidades - Saída Esperada: O nó Code deve retornar um array de objetos como
[{ json: { ... } }, ...]. Retornar apenas um objeto ou array causará erros, certifique-se de embrulhar suas saídas adequadamente - Debugging: Quando erros ocorrem, verifique que:
- Você não sobrescreveu ou removeu acidentalmente a propriedade json
- Sua saída final corresponde ao que n8n espera (um array de objetos)
- Em caso de dúvida, retorne um item simples inalterado para isolar problemas
- Deixe IA Ajudar: Para velocidade, clareza e precisão, use IA como assistente de escrita de código, forneça o erro/contexto e seu objetivo, e deixe ela sugerir e consertar seu código
- Editar e Testar Iterativamente: Após escrever código, execute testes de execução. Se algo quebrar, compartilhe a entrada, o código e a mensagem de erro ao buscar ajuda, essa clareza acelera debugging e suporte de IA
Melhores Práticas e Solução de Problemas
- Se seu nó code não está funcionando, verifique que a estrutura dos seus dados retornados corresponde exatamente ao que n8n espera (chave "json" deve apontar para um objeto)
- Não use imports globais (como import ou export), o nó code roda em sandbox. Use require se self-hosting e módulos externos estiverem habilitados
- Use variáveis integradas do n8n, como $input, para referenciar dados de outros nós para código limpo e confiável
- Comece simples e construa complexidade, teste com dados hardcoded se necessário antes de conectar entrada dinâmica
Estrutura de Retorno Obrigatória
IMPORTANTE: Formato de Retorno Correto
O nó Code DEVE retornar dados no seguinte formato:
return [{ json: { campo1: valor1, campo2: valor2 } }];
Erros comuns:
- Retornar apenas um objeto:
return { campo: valor }❌ - Retornar apenas um array:
return [valor1, valor2]❌ - Esquecer a propriedade "json":
return [{ campo: valor }]❌
Para debugging, compartilhe saída de erro, o código real e uma amostra do JSON recebido com IA ou a comunidade n8n para diagnóstico rápido.
O nó Code é a ferramenta definitiva para manipulação de dados sob medida no n8n - poderoso, rápido e previsível quando você conhece seus dados e domina a estrutura de retorno.