Seu primeiro workflow em 30 minutos

Field Note

A pessoa abre o n8n pela primeira vez, vai direto nos templates e importa um "assistente de vendas com IA" de 23 nós. Pede credencial de seis serviços. Ela preenche três, roda, e um nó no meio fica vermelho com uma mensagem sobre undefined. Qual nó mandou o dado errado? Ela não sabe, porque nunca olhou a saída de nenhum. Fecha a aba e conclui que "n8n é complicado". Não era o n8n. Era começar pelo nó 23 sem ter entendido o nó 1.

Conceito

O primeiro workflow tem um único objetivo: você ver o dado passar de um nó para o outro e entender o que aconteceu em cada passo. Três nós bastam.

Manual Trigger. Todo workflow precisa de um trigger. O Manual Trigger é o que dispara quando você clica em Execute workflow. Serve para testar e para workflows que não devem rodar sozinhos. Só pode existir um por workflow: um segundo dá erro.

HTTP Request. O nó que chama qualquer endereço na web e devolve a resposta. Os campos principais são Method (GET, POST e outros) e URL. Com ele você fala com qualquer API, mesmo as que não têm nó pronto. Vamos usar a BrasilAPI, uma API pública brasileira, sem chave, que também é uma das fontes que o nó CNPJ Hub do meu laboratório consulta. O endpoint de CEP é este:

https://brasilapi.com.br/api/cep/v1/01310100

Pela documentação da API, a resposta traz campos como cep, state, city, neighborhood, street e service (qual provedor respondeu). CEP inexistente devolve erro 404.

Edit Fields (Set). O nó que monta a saída do jeito que você quer: renomeia, escolhe, cria campos. No modo Manual Mapping, você arrasta um campo do painel INPUT para Fields to Set e o n8n escreve a expressão por você, algo como {{ $json.city }}. Cada campo tem o seletor Fixed | Expression: fixo é texto literal, expressão é dado vivo.

Ler a saída. Cada nó abre num painel com a entrada à esquerda e a saída à direita. Em OUTPUT você alterna a visualização, e a opção JSON mostra o dado cru. Lembre da estrutura: uma lista de itens, cada um com seus campos. Para rodar só um nó, use Execute step dentro dele. Para rodar tudo, Execute workflow no canvas.

Pin data. Depois que o HTTP Request respondeu, você pode fixar essa saída com o ícone Pin data. Os próximos testes reaproveitam o dado sem chamar a API de novo. Vale só para teste: em produção, o pin é ignorado.

Não precisa publicar. Execução manual não conta na cota do Cloud e não exige Publish. Publicar é para quando um trigger automático entra em cena.

Quando usar

• Primeiro contato com o n8n, antes de qualquer template.
• Para testar uma API nova: Manual Trigger, HTTP Request e leitura da resposta, antes de construir o fluxo de verdade.
• Para depurar um workflow grande. Isole o trecho suspeito num workflow de três nós.
• Para ensinar alguém do time. Três nós cabem numa tela e numa conversa.

Quando não usar

• Como workflow de produção. Manual Trigger depende de alguém clicar.
• Com API que pede chave logo de cara. Credencial é assunto para depois que a leitura de saída virou hábito.
• Com dado real de cliente no primeiro teste. Use dado público.

Faça agora

O entregável é o Primeiro workflow rodando: Manual Trigger, HTTP Request e Edit Fields, com a saída final legível e anotada.

1. No n8n, clique em Create workflow. Renomeie para primeiro-workflow-cep clicando no nome.
2. Clique em Add first step, busque Manual Trigger e adicione.
3. Clique no + depois do trigger, busque HTTP Request e adicione. Deixe Method em GET e cole a URL do Conceito em URL. Não mexa em Authentication.
4. Dentro do nó, clique em Execute step. Em OUTPUT, abra a visualização JSON e leia a resposta inteira. Anote os nomes dos campos e qual service respondeu.
5. Fixe essa saída com Pin data.
6. Clique no + depois do HTTP Request e adicione Edit Fields (Set). Modo Manual Mapping.
7. Arraste do INPUT para Fields to Set os campos street, city e state. Renomeie para rua, cidade e uf. Confira que o valor de cada um virou expressão, como {{ $json.street }}.
8. Crie um quarto campo consultado_em, em modo expressão, com o valor {{ $now.toISO() }}.
9. Ligue a opção que descarta o resto, Keep Only Set Fields, rode com Execute step e confira em OUTPUT que só sobraram os quatro campos.
10. Volte ao canvas e clique em Execute workflow. Os três nós devem ficar verdes.
11. Teste o erro: tire o pin do HTTP Request (link Unpin no aviso), troque o CEP por 00000000 e rode de novo. Anote a mensagem.
12. Volte o CEP válido, rode de novo e preencha o registro abaixo.

Armadilhas

• Começar pelo template gigante. Você herda 23 decisões que não tomou.
• Não abrir a saída. Nó verde não significa dado certo. Leia o JSON.
• Digitar a expressão na mão. Arrastar do INPUT evita erro de nome de campo.
• Esquecer o pin ligado. Você muda a URL, roda, e o resultado não muda. O pin estava lá.
• Achar que precisa publicar. Manual Trigger roda com Execute workflow. Publish é para trigger automático.
• Confiar que API pública nunca cai. Ela cai. Foi por isso que o CNPJ Hub nasceu com fallback entre seis fontes. No primeiro workflow, só observe o erro e anote.

Material para levar

PRIMEIRO WORKFLOW RODANDO

Nome do workflow:
Data:

Nó 1: Manual Trigger
  Saída (quantos itens):

Nó 2: HTTP Request
  Method:
  URL:
  Campos que vieram na resposta:
  Provedor que respondeu (service):
  Pin data usado?  sim / não

Nó 3: Edit Fields (Set)
  Modo:
  Campo final | Expressão
  rua         |
  cidade      |
  uf          |
  consultado_em |
  Keep Only Set Fields ligado?  sim / não

Teste de erro
  CEP usado:
  Mensagem recebida:
  Em qual nó parou:

Saída final (cole o JSON):

O que eu faria diferente:

Checklist rápido:

Um trigger, um HTTP Request, um Edit Fields
Execute step em cada nó, leitura do JSON em cada saída
Campos arrastados do INPUT, nunca digitados
Pin para testar, Unpin antes de mudar a URL
Erro provocado e anotado
Nada publicado