Ilustrativo — três camadas de configuração alimentam o workflow, que produz sua primeira execução.
🧰 n8n ou Make — a escolha
A primeira decisão da construção é qual plataforma vai hospedar seus fluxos. Você não precisa das duas — precisa dominar uma. As candidatas são n8n (open-source, self-host ou cloud, com escape para código) e Make (no-code, 100% hospedado, rápido de começar).
✓ Escolha n8n quando
- ✓Quer controlar os dados (self-host) e fugir de cobrança por operação.
- ✓Precisa de lógica complexa: Code node em JS/Python quando o visual não basta.
- ✓Volume alto de execuções — custo previsível por instância, não por passo.
- ✓Quer versionar o fluxo como JSON e levar de um cliente para outro.
✗ Evite começar por Make se
- ✗Vai rodar dezenas de milhares de operações/mês — a conta por operação explode.
- ✗Precisa de dados on-premise por compliance — Make é só cloud.
- ✗Quer lógica que foge do no-code; o code custom é mais limitado.
- ✗Quer evitar lock-in — exportar/portar é mais fácil no n8n.
💡 Dica prática
Comece com n8n cloud (trial) para aprender sem instalar nada. Quando o fluxo provar valor e o volume crescer, migre para self-host (Docker) — o mesmo JSON do fluxo importa direto. Aprenda a ferramenta, depois otimize o hosting.
Você controla custo e dados
Zero infra, paga assinatura
Escape para lógica complexa
Portabilidade do fluxo
👤 Contas e credenciais
Uma credential guarda o acesso a um serviço uma vez e é reutilizada em todos os nodes que falam com ele. Você cadastra a conexão com o Gmail, OpenAI ou Supabase uma vez; cada node só aponta para ela.
🔗 Conta de serviço dedicada
Nunca conecte sua conta pessoal. Crie uma conta de serviço só para a automação (ex.: automacao@empresa.com). Assim você revoga o acesso sem afetar ninguém e sabe exatamente o que a automação tocou.
- •Permissões mínimas — só os escopos que o fluxo realmente usa.
- •OAuth quando o serviço suporta (token expira e renova); API key quando não.
- •Nomeie a credential pelo ambiente: OpenAI · prod vs OpenAI · staging.
Formato por serviço
Quando usar cada um
Menor privilégio
Não usar a pessoal
🔑 Chaves de API e variáveis de ambiente
Tudo que muda entre dev e produção — chaves, URLs, IDs de planilha — vive em variáveis de ambiente, fora dos nodes. No self-host, isso é um arquivo .env; no fluxo você lê com $env.
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx SUPABASE_URL=https://abcd.supabase.co SUPABASE_SERVICE_KEY=eyJhbGciOi... SLACK_ALERT_WEBHOOK=https://hooks.slack.com/services/... ENVIRONMENT=production
// no campo de header de um HTTP Request node: Authorization: Bearer ={{ $env.OPENAI_API_KEY }} // escolher comportamento por ambiente: ={{ $env.ENVIRONMENT === 'production' ? 'real' : 'sandbox' }}
💡 Dica prática
Mantenha um .env.example versionado, com as chaves sem valor. Assim qualquer pessoa (ou você daqui a 3 meses) sabe quais variáveis o fluxo precisa, sem nunca expor o segredo de verdade.
🔒 Segurança e gestão de segredos
O erro mais caro de iniciante é vazar uma chave. Uma key de LLM exposta no GitHub vira fatura de milhares de reais em horas, porque bots varrem repositórios públicos atrás disso.
⚠️ Onde os segredos vazam (e como evitar)
- ✗Colar a chave no corpo de um node em vez de usar credential/$env.
- ✗Logar o objeto inteiro da requisição (que inclui o header Authorization).
- ✗Retornar dados sensíveis no response do webhook por engano.
- ✗Commitar o .env — sempre no .gitignore.
✓ Práticas seguras
- ✓Rotacionar chaves periodicamente e ao menor sinal de vazamento.
- ✓Menor privilégio: a chave só pode o que o fluxo precisa.
- ✓Mascarar dados em logs (sk-***).
- ✓Usar um secret manager quando a operação cresce.
✗ Hábitos perigosos
- ✗Uma única chave "admin" para tudo.
- ✗Mandar print do workflow com a chave visível no chat.
- ✗Reusar a mesma chave em staging e produção.
- ✗Nunca revogar chaves de ex-projetos.
🧩 Estrutura de um workflow
Um workflow é um grafo de nodes ligados por conexões. Cada conexão carrega uma lista de itens em JSON. Internalize isto: tudo é uma lista de itens fluindo de node em node — esse é o modelo mental que destrava todo o resto da trilha.
Trigger
Onde o fluxo começa
Um node especial que inicia a execução: manual, webhook, agenda ou evento externo. Todo workflow tem exatamente um ponto de partida.
Nodes de ação
O que faz o trabalho
Cada node recebe itens, transforma e devolve itens. HTTP Request, Set, IF, código, Gmail — todos seguem entra-item / sai-item.
Itens e $json
O dado que viaja
Dentro de qualquer node, $json é o item atual. Se a entrada tem 50 itens, o node roda 50 vezes (uma por item) — automático.
{
"json": {
"nome": "Ana Souza",
"email": "ana@empresa.com",
"valor": 1290.50
}
}
// no próximo node, acessa com: ={{ $json.email }}
👋 Primeiro "hello world"
A prova de que o ambiente funciona: um Manual Trigger ligado a um node que define um campo. Você executa, vê o dado nascer no primeiro node e chegar no segundo. Simples — e elimina 90% da ansiedade de começar.
Adicione um Manual Trigger
No canvas vazio, clique em "+", busque Manual Trigger. Ele é o botão "Test workflow".
Ligue a um node Edit Fields (Set)
Crie um campo mensagem com valor Hello World. Conecte a saída do trigger à entrada do Set.
Execute e leia a saída
Clique "Test workflow". Abra o node Set e veja o item de saída — seu primeiro dado fluindo de ponta a ponta.
[
{ "mensagem": "Hello World", "executadoEm": "={{ $now }}" }
]
💡 Dica prática
Antes de qualquer fluxo real, sempre comece com um "hello world" da integração que vai usar (1 chamada à API, 1 linha na planilha). Provar a conexão isolada economiza horas de debug depois.
📌 Resumo do Módulo
Próximo Módulo:
4.2 - Primeira automação ponta a ponta (do trigger à ação, com IA no meio)