# n8n: conceitos fundamentais, nós e automação

> Guia prático completo sobre o n8n: desde a instalação e conceitos básicos (gatilhos, nós, variáveis) até a criação de fluxos de trabalho autônomos com IA sem limitações.

n8n é uma ferramenta poderosa de código aberto que permite automatizar tarefas rotineiras e integrar aplicações sem exigir conhecimentos profundos de programação. Imagine: dados do Google Sheets são enviados automaticamente para o Telegram, enquanto notificações do Trello chegam ao seu email — tudo isso sem esforço adicional. É ideal tanto para iniciantes quanto para profissionais que desejam otimizar seus fluxos de trabalho.

Este guia ajudará você a dominar os fundamentos do n8n: desde a instalação até a criação dos primeiros workflows. Vamos explorar conceitos-chave e passos práticos para que você comece imediatamente a automatizar suas operações!

## 1. Interface do Editor n8n

### Visão Geral

O editor é centrado na tela (canvas) — o principal espaço de trabalho para construir cadeias de automação. A partir daqui, você acessa todos os workflows, credenciais e materiais de referência.

![Visão geral da interface do canvas do Workflow Editor do n8n](/api/guides-media/automation/n8n-basics/images/945a2957d9ceafa9b50e624b97ee0467b809b7cf3af2f31b6e24d2d144721935.webp)

### Painel Esquerdo

1. Localize o logotipo do n8n no canto superior esquerdo.

2. Clique no ícone com um círculo e uma seta abaixo do logotipo.

3. Um menu com seis seções será aberto:

● **Painel de Administração (Admin Panel)**: para usuários do n8n.cloud, gerenciar configurações da plataforma.

● **Workflows**: criar, salvar e editar processos.

● **Credenciais (Credentials)**: configurar autenticação e chaves de API para serviços externos.

● **Execuções (Executions)**: registro completo das execuções de processos (abre em nova janela; execuções interrompidas não são contabilizadas aqui).

● **Ajuda (Help)**: acesso à documentação oficial, fórum, biblioteca de templates e informações sobre a versão.

● **Atualizações (Updates)**: detalhes sobre a versão atual e releases disponíveis.

Na seção Help, também há um link para a comunidade oficial de desenvolvedores no Discord — lá você pode encontrar respostas práticas para dúvidas não cobertas pela documentação básica.

### Barra Superior

1. No canto superior esquerdo, especifique o nome do workflow atual:

```
00n8n + Personal My workflow + Add tag
Inactive Share Save
```

2. Adicione tags ao lado do nome para facilitar a organização por temas ou projetos.

3. No canto superior direito, clique em **Save** para salvar o workflow.

4. Use o interruptor ao lado para ativar/desativar o processo (disponível apenas quando houver um nó trigger).

Atenção: um workflow não salvo pode ser perdido ao fechar o navegador — certifique-se de salvar as alterações manualmente antes de fechar a aba.

### Canvas (Tela)

1. O canvas é um fundo cinza com grade de coordenadas:

![Barra de navegação e controles dos elementos do canvas do n8n](/api/guides-media/automation/n8n-basics/images/2d1fe67e701cc13b428c977cd6eeace6e5bc264d990d25ce51f010c7986745f6.webp)

2. Encontre os cinco botões principais de controle:

● **+** e **-** na lupa para ajustar o zoom.

● **←** para resetar rapidamente o zoom para 100%.

● **Execute Workflow** para iniciar manualmente o processo, do Start ou triggers até o nó final ou erro.

● **+** laranja para abrir a biblioteca de nós disponíveis.

3. No centro está o nó inicial **Start**, com o ícone verde "Play".

### Movendo o Canvas

1. Segure `Ctrl` (ou `Cmd` no Mac) + botão esquerdo do mouse e arraste o canvas.

2. Ou use dois dedos no trackpad para deslocamento suave.

3. O canvas suporta totalmente o controle via mouse: scroll do mouse — zoom, botão direito do mouse — abre o menu contextual rápido. Isso acelera significativamente a navegação em diagramas grandes.

## 2. Arquitetura e Tipos de Nós (Nodes)

### Fundamentos dos Nós

1. Os nós são blocos básicos de construção para processamento de dados (entrada, transformação, saída).

2. Existem dois tipos principais:

● **Nós Comuns (Regular node)**: editam, transformam, consultam ou enviam dados.

● **Nós Trigger (Trigger node)**: iniciam o processo e fornecem dados iniciais baseados em eventos ou agendamento.

Cada nó pode ser configurado precisamente para a tarefa: definir parâmetros, alterar campos, conectar variáveis de ambiente. Ao passar o mouse sobre a seta de saída, é exibida a quantidade de itens de dados passados adiante na cadeia.

Os nós são conectados em sequências lineares — a execução sempre flui da esquerda para a direita.

### Nós Principais (Core nodes)

1. Use-os para operações básicas: agendamento (**Schedule**, **Interval**) ou escrita de código próprio (**Code**, **Function**).

Os nós Code e Function permitem executar JavaScript ou Python customizado quando os nós padrão existentes são insuficientes.

Schedule define um cronograma (por exemplo, diariamente às 09:00), enquanto Interval executa o processo a cada N minutos. Esses nós formam a base de automações que não dependem de webhooks externos.

### Nó Inicial (Start node)

1. Aparece automaticamente em cada novo workflow.

2. Não pode ser excluído nem duplicado.

3. Se não for necessário, basta desativá-lo e movê-lo para o lado, removendo a linha de conexão.

4. Para múltiplos pontos de partida, adicione nós trigger adicionais ou crie um workflow separado.

Mesmo que o Start não seja utilizado em produção, ele ajuda a testar manualmente ramos específicos da cadeia durante o desenvolvimento.

### Busca e Adição de Nós

1. Abra o painel de adição de nós de uma das três formas:

● Clique em **+** no canto superior direito do canvas.

● Clique em **+** à direita da saída de qualquer nó.

● Arraste a linha de conexão a partir do ponto de saída do nó para a direita ou pressione a tecla `Tab`.

2. O painel contém filtros por categoria: All, Regular, Trigger.

3. Os nós estão agrupados por áreas: Analytics, Communication, Development, Marketing, Sales, etc.

4. Digite o nome do serviço desejado na barra de busca.

Se você não souber o nome exato do serviço, insira palavras-chave gerais: `email`, `webhook`, `sheets`, `telegram` — o n8n sugerirá automaticamente integrações relevantes.

### Adicionando Nós

1. Clique no nó desejado na lista do painel.

2. O nó aparecerá instantaneamente no canvas e será conectado ao bloco previamente selecionado.

### Botões nos Nós

1. Passe o cursor do mouse sobre um nó:

![Menu contextual de ações rápidas no nó (ativação, exclusão, teste)](/api/guides-media/automation/n8n-basics/images/26e3b4d4948dfbe72a35ac527e7536f998d6b30be54ca0e21821a4fee0db08f7.webp)

2. Use os ícones rápidos:

● **Lixeira**: excluir o nó.

● **Pausa**: desativar/ativar o nó sem excluí-lo.

● **Copiar**: criar um duplicado com todas as configurações.

● **Play**: executar apenas este nó específico para teste rápido.

Após a execução do nó, a aba **Output** é aberta, mostrando claramente a estrutura dos dados retornados.

### Movendo o Workflow

1. Selecione todos os nós usando `Ctrl + A` (ou `Cmd + A`).

2. Arraste qualquer nó selecionado para uma nova posição no canvas.

## 3. Trabalhando com Dados: JSON, Arrays e Binary

Nesta seção, analisaremos como o n8n estrutura e processa fluxos de informação.

### Que tipos de dados existem?

No n8n, os dados são divididos em dois formatos: **JSON** e **Binary**.

1. **JSON** — formato textual estruturado, semelhante a um dicionário. É usado para transmitir parâmetros entre serviços (nomes, preços, datas, listas de pedidos).

2. **Binary** — dados binários não textuais: imagens, documentos PDF, áudios ou arquivos compactados.

Na grande maioria das vezes, nas automações, você trabalhará com JSON. O resultado é sempre visível no painel de resultados à direita de qualquer nó, na aba "JSON".

### O que é JSON?

O JSON armazena informações no formato de pares `"chave: valor"`:

● Todos os objetos são envolvidos por chaves `{}`.

● Chave e valor são separados por dois-pontos `:`, e pares distintos são separados por vírgulas `,`.

### Exemplo Simples

```json
{
    "name": "Емма"
}
```

Aqui, `"name"` é o nome do campo (chave), e `"Emma"` é seu valor. Todas as strings devem estar obrigatoriamente entre aspas duplas.

### Adicionando Mais Detalhes

```json
{
  "name": "Емма",
  "age": 27,
  "is_smoking": false,
  "car": {
    "model": "Chevrolet Camaro",
    "color": "бежевий"
  },
  "pets": [
    {
      "type": "собака",
      "name": "Чарлі"
    },
    {
      "type": "хом'як",
      "name": "Ніксон"
    }
  ]
}
```

● `"age": 27` — número, escrito sem aspas.

● `"is_smoking": false` — valor booleano (true/false), também sem aspas.

● `"car"` — objeto JSON aninhado.

● `"pets"` — array (lista), envolvido por colchetes `[]`.

### O que é um Array?

Um array é uma lista ordenada de elementos. É escrito entre colchetes `[]` e pode conter textos, números ou outros objetos.

### Como os dados são transmitidos entre nós?

O n8n sempre transmite dados como um **array de objetos**. Por exemplo:

```json
[
    {
        "name": "Емма",
        "age": 27
    },
    {
        "name": "Петро",
        "city": "Київ"
    }
]
```

Cada elemento do array é processado pelo próximo nó sequencialmente ou em paralelo.

### O que é Binary?

Dados binários são armazenados em um objeto especial de serviço:

```json
"binaryKeyName": {
  "data": "...",
  "mimeType": "image/png",
  "fileExtension": "png",
  "fileName": "example.png"
}
```

Os bytes do arquivo são codificados no formato Base64.

## 4. Conexões e Interação entre Nós

### O que um nó pode fazer?

Um nó é um bloco funcional que executa uma operação específica:

● Obter dados da API de um serviço de terceiros.

● Enviar notificações para chats do Telegram, Discord ou email.

● Baixar, editar ou salvar arquivos.

Veja como fica a interface de um nó aberto:

![Janela de parâmetros detalhados e configurações de um nó individual](/api/guides-media/automation/n8n-basics/images/2b2be28c4a62a182c63844ae7fed81d3bc2a99e65d25ac54aed907c8ec9da527.webp)

Dentro, há abas: **Parameters** (configuração da lógica), **Output** (dados de saída), **Settings** (timeouts, novas tentativas em caso de erro).

### Conectando Nós

Os nós são unidos por setas. Estas são as rotas pelas quais a informação flui:

● Uma seta pode bifurcar de um nó para vários (envio paralelo).

● Vários ramos podem convergir para um nó de fusão (**Merge**).

Diagrama de interação de múltiplos nós:

![Diagrama de interação de nós em uma cadeia de automação do n8n](/api/guides-media/automation/n8n-basics/images/a4a27cc18966b75486e57469136f1d4ffdb47e77b246a6a26bdf1995ad1f344b.webp)

## 5. Triggers: Webhook, Schedule e Eventos

### O que é um Trigger?

Um Trigger é o nó inicial que "desperta" o workflow quando ocorre um evento externo específico.

### Principais Tipos de Triggers

1. **Webhook**: dispara quando chega uma requisição HTTP (GET, POST, etc.) de um site ou aplicação externa.

2. **Schedule Trigger**: execução periódica baseada em cronograma ou expressão CRON:

![Configuração do nó Trigger Schedule para execução periódica conforme agendamento](/api/guides-media/automation/n8n-basics/images/f498e65a269b87f0ac7c2dd49d2649d44c85a92f806fb9e58b4454d2e6858833.webp)

3. **App Triggers**: monitoramento de eventos em serviços específicos (nova linha no Google Sheets, novo lead no CRM ou reação a mensagem no Telegram).

## 6. Modos de Operação: Test vs Production

O n8n oferece dois modos fundamentais:

1. **Modo de Teste (Test)** — depuração interativa com visualização de cada etapa.

2. **Modo de Produção (Production)** — operação autônoma contínua em segundo plano.

## 7. Configuração Passo a Passo e Teste de Webhook

1. Adicione o nó **Webhook** ao canvas.

![Visão geral da interface do canvas do Workflow Editor do n8n](/api/guides-media/automation/n8n-basics/images/945a2957d9ceafa9b50e624b97ee0467b809b7cf3af2f31b6e24d2d144721935.webp)

2. Adicione o nó **Edit Fields (Set)** para modificar os dados:

![Seleção e adição do nó Edit Fields (Set) para transformação de dados](/api/guides-media/automation/n8n-basics/images/2bda08fce1411acf15aae4e73e3afef4a3826381e86feb6d80206ba0267b6bc9.webp)

3. Configure o campo `success` com o valor `true`:

![Configuração de campos de entrada e atribuição de valores no nó Set](/api/guides-media/automation/n8n-basics/images/861631d521613a4684ff9841ae60e409b4ba6ec6f686763abfeff957b95097e4.webp)

4. Clique em **Test step / Listen for test event**:

![Execução de teste do nó Webhook e geração de URL para receber dados de entrada](/api/guides-media/automation/n8n-basics/images/96467279ae2b961ef1398cf07def9245f5fad26722d6fc8f51354c6c2d08deef.webp)

5. Copie o **Test URL** gerado:

![Copiando a URL de teste do webhook para enviar requisições via navegador ou curl](/api/guides-media/automation/n8n-basics/images/46a18e8ca341a5ba5f5d09bfdabdd828291abb120f2986a78ec379e4efde26ad.webp)

6. Envie a requisição via navegador, Postman ou cURL. Em resposta, o n8n retornará o JSON gerado:

![Exibição da resposta JSON bem-sucedida do n8n na janela do navegador](/api/guides-media/automation/n8n-basics/images/8cdcd70d7e337cfa1e48698c298e7807d3022e6777d7a3d6aeb698ef66e898de.webp)

7. Altere os parâmetros e execute o teste novamente, garantindo a correção da transformação:

![Repetição do teste com valores de parâmetros alterados e validação dos dados atualizados](/api/guides-media/automation/n8n-basics/images/4c2be16352c2179afa475af6ee5b08420c03ca0755bc7c4ade41b6d5858d8962.webp)

## 8. Transição para Modo de Produção (Production)

Quando o workflow foi testado:

1. Abra o nó Webhook e copie a **Production URL**:

![Obtendo a URL de Produção ativa para execução real do webhook no n8n](/api/guides-media/automation/n8n-basics/images/4b429613856c10cd6548da729388b9715e6393c267f22db2055da47ee148bc21.webp)

2. Mova o interruptor na barra superior para a posição **Active**:

![Ativação do workflow através do switch na barra superior de controle do n8n](/api/guides-media/automation/n8n-basics/images/197596a4c909ccae9482a36bfa6e9ac719bae2099230ee7545e27e0d347167da.webp)

3. Agora o n8n processará todas as chamadas reais de entrada em segundo plano, e o histórico de execução pode ser consultado na seção **Executions**.

## 9. Conclusões e Dicas Práticas

Você dominou os conceitos básicos do n8n: arquitetura do canvas, tipos de nós, transmissão de estruturas JSON, triggers e alternância entre ambientes de teste e produção. Esta é uma base sólida para construir agentes de IA autônomos complexos e automatizar qualquer processo de negócio!