No n8n, tudo que passa entre um node e outro é um array de objetos, e cada objeto embrulha os dados reais dentro de uma chave chamada json. Parece detalhe de documentação, mas é a causa direta de metade dos erros de quem está aprendendo: expressão que devolve vazio, node que roda vezes demais, campo que "existe mas não aparece". Depois que você enxerga esse formato, esses três problemas viram um só, e ele tem solução óbvia.
Neste artigo
O formato, exatamente como ele é
A estrutura oficial é esta:
[
{
"json": {
"apple": "beets",
"carrot": { "dill": 1 }
},
"binary": {
"apple-picture": {
"data": "....",
"mimeType": "image/png",
"fileExtension": "png",
"fileName": "example.png"
}
}
}
]Três camadas, e cada uma tem um motivo:
1. Os colchetes externos. É sempre uma lista, mesmo quando há um único registro. Um item só continua sendo uma lista de um item.
2. A chave json. Os seus dados ficam aqui dentro. Ela existe para separar dado estruturado de arquivo.
3. A chave binary. Opcional, e só aparece quando o item carrega arquivo — PDF, imagem, planilha. Dentro dela, data é obrigatório e traz o conteúdo codificado; mimeType, fileExtension e fileName são recomendados.
Arquivo não fica dentro de json. Se você está procurando o PDF que chegou no e-mail e não acha, é porque está olhando no lugar errado: ele está em binary, e a chave dentro dela tem o nome que o node de origem deu — normalmente algo como data ou o nome do anexo.
Por que isso causa o erro mais comum
Você olha a saída do node e vê um campo chamado nome. Escreve a expressão apontando para ele e volta vazio.
O motivo quase sempre é a camada que a interface esconde. A tela mostra o conteúdo de json já desembrulhado, para facilitar a leitura. Mas quando você escreve a expressão à mão, precisa considerar o caminho real.
A forma de acessar o campo do item atual é {{ $json.nome }} — o $json já aponta para dentro do embrulho. Se o campo estiver aninhado, você desce com pontos: {{ $json.nested.campo }}.
Existe um jeito de nunca errar isso: arraste o campo do painel de entrada para dentro da caixa, em vez de digitar. O n8n escreve a expressão sozinho, com o caminho certo, incluindo os níveis aninhados. Digitar à mão só quando o campo não estiver visível.
Por que o node roda várias vezes
Como o dado é uma lista, o node processa cada item individualmente e executa a operação configurada para cada um.
Um exemplo direto da documentação: se você configura um node para criar um cartão e monta uma expressão pegando o nome do dado que chegou, esta entrada cria dois cartões, um chamado test1 e outro test2:
[
{ "name-input-value": "test1" },
{ "name-input-value": "test2" }
]Você configurou um node. Ele fez duas coisas. Não há repetição escrita em lugar nenhum — está implícita no formato.
É essa mecânica que explica o acidente clássico: o node de busca devolveu 300 contatos em vez dos 3 esperados, e o node seguinte disparou 300 mensagens obedientemente.
Dado aninhado: o que a tabela esconde
Quando um campo contém outra estrutura dentro dele, a interface mostra em forma de tabela e destaca que aquele campo tem conteúdo aninhado. O caminho para chegar lá é sempre descendo com pontos, na ordem em que os níveis aparecem.
É aqui que aparece aquele resultado esquisito em que a expressão devolve algo como [object Object] em vez do valor. Isso significa que você parou num nível intermediário — apontou para a caixa, não para o que está dentro dela. A correção é continuar descendo até chegar ao valor final.
A exceção do node Code
Um detalhe que evita frustração: dentro do node Code, o n8n é tolerante. Desde a versão 0.166.0, ele adiciona a chave json automaticamente se você esquecer, e embrulha o retorno em array se necessário.
Ou seja, dentro do Code você pode devolver o objeto direto que funciona. Mas essa tolerância vale só ali — quem constrói node próprio precisa devolver o formato completo, com a chave json explícita.
Grave três coisas: sempre é lista, os dados moram dentro de json, arquivo mora em binary. Com isso, expressão vazia e node repetindo deixam de ser mistério.
Esta aula faz parte do Curso de n8n do zero ao avançado, com todas as aulas em portugues.
Perguntas frequentes
Qual é a estrutura de dados do n8n?
Todo dado que passa entre nodes é um array de objetos. Cada objeto tem uma chave json, onde ficam os dados estruturados, e opcionalmente uma chave binary, onde ficam arquivos com o conteúdo codificado e informações como tipo e nome.
Por que minha expressão retorna vazio?
Normalmente porque o caminho está incorreto — o campo está um nível mais fundo do que você apontou, ou o nome tem diferença de maiúsculas. A forma mais segura de resolver é arrastar o campo do painel de entrada para dentro da caixa, deixando o n8n escrever o caminho.
Por que o node executa várias vezes?
Porque recebeu vários itens. O node processa cada item individualmente e repete a operação para cada um. Se ele executou trezentas vezes, o node anterior devolveu trezentos itens — verifique a contagem na saída antes de ativar o fluxo.
Onde ficam os arquivos que chegam no fluxo?
Na chave binary do item, nunca dentro de json. Ali o conteúdo fica codificado no campo data, acompanhado de informações opcionais como mimeType, fileExtension e fileName.
Preciso escrever a chave json no node Code?
Não é obrigatório. Desde a versão 0.166.0, o node Code adiciona a chave automaticamente quando ela falta e embrulha o retorno em array se preciso. Essa tolerância existe apenas nos nodes Code e Function — ao criar um node próprio, o formato completo é obrigatório.
