Pular para o conteúdo principal

Lógica e Manipulação de Dados no n8n: Workflows Inteligentes e Práticos

info

Esta seção apresenta os fundamentos técnicos, arquitetura e conceitos de lógica e dados do n8n. Para guias práticos, passo a passo e troubleshooting, acesse a seção Usando n8n.

info

Veja o guia completo: Estrutura de Dados no n8n — padrão, exemplos, boas práticas e diagrama visual.

Resumo Técnico: Estrutura de Dados no n8n​

No n8n, todos os dados trafegam entre os nós como um array de objetos. Cada item pode conter:

  • json
    : dados estruturados (campos, valores, objetos aninhados)
  • binary
    (opcional): arquivos anexos, com 
    data
    , 
    mimeType
    , 
    fileExtension
    , 
    fileName

Consulte a página Estrutura de Dados no n8n para detalhes avançados, exemplos genéricos e diagrama visual.

Casos de Uso no Brasil​

Veja exemplos completos e dicas para automações nacionais:

Dados​

  • Tipos de Dados: Strings, números, objetos, arrays
  • Manipulação: Transformação e formatação
  • Validação: Verificação de dados
  • Conversão: Mudança de tipos

Lógica de Fluxo​

  • Condicionais: IF/ELSE e decisões
  • Loops: Repetição de operações
  • Merge: Combinação de fluxos
  • Error Handling: Tratamento de erros

Conexões​

  • Tipos de Conexão: Sucesso, erro, condicional
  • Mapeamento de Dados: Passagem entre nodes
  • Transformação: Modificação durante passagem

Conceitos Fundamentais​

Estrutura de Dados​

No n8n, todos os dados trafegam entre os nodes como um array de objetos, chamados de items. Cada item representa uma unidade de informação processada no workflow.

Estrutura de Dados no n8n​

No n8n, todos os dados trafegam entre os nodes como um array de objetos, chamados de items. Cada item representa uma unidade de informação processada no workflow.

Estrutura Padrão de um Item​

Cada item possui, no mínimo, a chave 

json
(com dados estruturados) e, opcionalmente, a chave 
binary
(para arquivos e dados binários):

[
  {
    "json": {
      "nome": "João Silva",
      "email": "joao@exemplo.com",
      "idade": 30
    }
  },
  {
    "json": {
      "nome": "Maria Souza",
      "email": "maria@exemplo.com",
      "idade": 28
    },
    "binary": {
      "arquivo": {
        "data": "base64...",
        "mimeType": "application/pdf",
        "fileName": "contrato.pdf",
        "fileExtension": "pdf"
      }
    }
  }
]
Explicação dos Campos​
  • json: Objeto com dados estruturados (campos, valores, objetos aninhados).
  • binary: Objeto para dados binários (arquivos, imagens, documentos).
    • data: Conteúdo do arquivo em base64.
    • mimeType: Tipo MIME do arquivo (ex: 
      image/png
      , 
      application/pdf
      ).
    • fileName: Nome do arquivo original.
    • fileExtension: Extensão do arquivo (ex: 
      png
      , 
      pdf
      ).
Boas Práticas​
  • Sempre defina 
    mimeType
    , 
    fileName
    e 
    fileExtension
    ao trabalhar com arquivos binários para garantir compatibilidade e rastreabilidade.
  • Use a chave 
    json
    para todos os dados estruturados e reserve 
    binary
    apenas para arquivos.
  • Lembre-se: todos os nodes recebem e retornam arrays de items, mesmo que haja apenas um item no array.
Visualização e Debug​

Você pode inspecionar a estrutura dos dados em cada etapa do workflow usando o node Debug ou a visualização de execução do n8n.

Visualização da Estrutura de Dados (Mermaid.js)​

Nota importante: A padronização da estrutura de dados facilita a criação de automações robustas, a integração entre diferentes nós e a manipulação de arquivos e informações em workflows complexos.

Tipos de Dados​

  • String: Texto e caracteres
  • Number: Números inteiros e decimais
  • Boolean: Verdadeiro ou falso
  • Array: Lista de valores
  • Object: Estrutura chave-valor
  • Date: Datas e timestamps

Manipulação de Dados​

  • Extração: Obter valores específicos
  • Transformação: Modificar formato ou estrutura
  • Validação: Verificar integridade
  • Enriquecimento: Adicionar informações

Processamento de Itens e Fluxo de Dados nos Nós​

No n8n, cada nó processa automaticamente todos os itens do array de entrada. Isso significa que, se um node recebe 10 itens, ele executará sua lógica 10 vezes, uma para cada item, de forma independente.

Como funciona a iteração​

  • Entrada: O node recebe um array de objetos (itens).
  • Processamento: Executa a ação para cada item individualmente (exemplo: criar um cartão no Trello para cada item).
  • Saída: Retorna um novo array, normalmente com a mesma quantidade de itens, mas os dados podem ser transformados, filtrados ou expandidos.

Exemplo prático: Trello Node​

Se você conectar um node Trello após um node que gera múltiplos itens (ex: uma lista de tarefas), o Trello criará um cartão para cada item automaticamente:

Paralelismo e múltiplos ramos​

  • Ramos paralelos: Quando um workflow se divide (ex: IF, Switch), cada ramo processa os itens de forma independente e paralela.
  • Ordem de execução: O n8n executa todos os ramos em paralelo, mas a ordem de chegada dos resultados pode variar. Se precisar sincronizar, use o node Merge.
  • Always Output Data: Use esta opção em ramos que podem não gerar saída, para garantir que o fluxo continue sem erros.

Boas práticas​

  • Sempre que possível, projete seus workflows para processar múltiplos itens em lote, aproveitando o paralelismo nativo do n8n.
  • Use o node Merge para reunir dados de diferentes ramos antes de etapas finais.
  • Teste com diferentes quantidades de itens para garantir que o fluxo se comporte como esperado.

Nota importante: O processamento item a item é automático e transparente para o usuário, tornando o n8n ideal para automações em escala, como envio de emails em massa, criação de múltiplos registros em sistemas externos ou processamento de grandes volumes de dados.

Técnicas Avançadas​

Agregações e Estatísticas​

  • Soma: Total de valores numéricos
  • Média: Valor médio de um conjunto
  • Contagem: Número de itens
  • Máximo/Mínimo: Valores extremos

Filtros e Seleção​

  • Filtros Condicionais: Seleção baseada em critérios
  • Ordenação: Organização por valores
  • Limitação: Redução de volume de dados
  • Deduplicação: Remoção de duplicatas

Mapeamento e Transformação​

  • Mapeamento Simples: Transformação 1:1
  • Mapeamento Complexo: Transformações condicionais
  • Join: Combinação de dados de fontes diferentes
  • Split: Divisão de dados em múltiplos fluxos

Debugging​

Ferramentas de Debug​

  • Debug Node: Visualização de dados em tempo real
  • Logs: Registro de execução
  • Error Handling: Captura e tratamento de erros
  • Validation: Verificação de dados

Boas Práticas​

  • Teste Incremental: Valide cada etapa
  • Documentação: Comente lógicas complexas
  • Versionamento: Controle de mudanças
  • Monitoramento: Acompanhe performance

Próximos Passos​

  1. Aprenda sobre Dados para entender tipos e manipulação
  2. Explore Lógica de Fluxo para controle de execução
  3. Pratique Debugging para troubleshooting

Recursos Relacionados​

Domine a manipulação de dados e crie workflows inteligentes com lógica poderosa!