n8n Binário e Dados

Quando Usar

Use esta habilidade quando um fluxo de trabalho n8n lê, transforma, armazena, envia, baixa ou transmite arquivos e campos binários, incluindo entradas de agentes multimodais e anexos de chat.

Trate arquivos enviados e URLs gerados como potencialmente sensíveis. Obtenha aprovação antes de enviar dados para um novo host externo, use o escopo de retenção e acesso mais restrito disponível, evite registrar bytes ou payloads base64 e não incorpore credenciais em URLs ou campos de fluxo de trabalho.

Cada item n8n carrega dois slots independentes: $json para dados estruturados e $binary para bytes de arquivo. Eles viajam lado a lado pelo fluxo de trabalho. O conteúdo do arquivo — o PDF, imagem ou zip real — reside em $binary, nunca em $json. Se você errar essa divisão, lerá um campo vazio, perderá um arquivo no meio do fluxo ou entregará a um agente de IA uma entrada de ferramenta que ele não pode usar.

Esta habilidade abrange onde o binário reside, como lê-lo e gravá-lo, como evitar que ele seja silenciosamente removido, a barreira rígida entre o binário e a fronteira da ferramenta do agente de IA, e por que as superfícies de chat precisam de uma URL em vez de bytes brutos.

As três regras que previnem 90% dos bugs binários

1. O conteúdo do arquivo está em $binary, não em $json. Após um download HTTP, um gatilho "Ler Arquivos" ou um gatilho de anexo de e-mail, os bytes ficam em $binary.<key>. $json contém metadados, na melhor das hipóteses. Ler $json.data para o conteúdo do arquivo não retorna nada.

2. O binário não pode cruzar a fronteira da ferramenta do agente de IA — em nenhuma direção. Argumentos de ferramentas e valores de retorno de ferramentas são apenas JSON. Uma imagem enviada não pode ser passada para uma ferramenta como um arquivo, e uma ferramenta não pode retornar bytes brutos. Pré-estágio para armazenamento e passe uma chave ou URL através de JSON em vez disso. Veja references/AGENT_TOOL_BINARY.md.

3. As superfícies de chat renderizam imagens por URL, não por $binary. Slack, Discord, Teams, Telegram, chat de webhook incorporado — nenhum deles lê o slot binário. A imagem precisa residir em algum lugar onde uma URL possa buscá-la. Veja references/CDN_REQUIREMENT.md.

Os dois slots

Cada item é moldado assim:

{
  "json": { "customerId": 42, "status": "sent" },
  "binary": {
    "invoice": {
      "data": "<base64-encoded bytes>",
      "mimeType": "application/pdf",
      "fileName": "invoice-42.pdf",
      "fileExtension": "pdf"
    }
  }
}

A chave dentro de binary (invoice aqui) é o nome da propriedade binária. A maioria dos nós de manipulação de arquivos tem um parâmetro binaryPropertyName que aponta para ela — o produtor nomeia o slot, o consumidor o referencia por esse nome. A chave padrão na maioria dos nós é data, então quando nada lhe diz o contrário, assuma $binary.data.

$json e $binary são namespaces separados. Uma expressão como {{ $binary.invoice.fileName }} lê metadados do arquivo; {{ $json.customerId }} lê dados. Eles nunca se misturam.

Essa divisão também explica um problema comum de webhook: um gatilho Webhook recebendo multipart/form-data coloca o arquivo enviado em $binary e os campos de formulário acompanhantes em $json.body — então um arquivo enviado não está em nenhum lugar sob $json. (A aninhamento $json.body para webhooks é território de sintaxe de expressão n8n.)

Veja references/BINARY_BASICS.md para a anatomia completa do slot, tipos MIME e limites de tamanho.

Produzindo binário

Raramente você constrói um slot $binary manualmente — os nós o preenchem para você:

Para um download HTTP, o único campo que importa é responseFormat. Confirme-o com get_node em nodes-base.httpRequest — deixá-lo no formato JSON/string padrão é a razão clássica pela qual um arquivo baixado acaba como texto ilegível em $json em vez de bytes limpos em $binary.

Lendo e gravando binário em um nó de Código

A maioria dos fluxos de trabalho nunca precisa abrir os bytes — eles apenas passam o binário para um consumidor (anexo de e-mail, upload de arquivo, arquivo do Slack). Quando você precisar dos bytes brutos, faça isso em um nó de Código.

Leia com getBinaryDataBuffer — não tente decodificar base64 $binary.<key>.data manualmente:

// Nó de Código, "Executar uma Vez para Cada Item"

…