🛠️ Construção

n8n é uma plataforma de automação open-source (self-host ou cloud) com lógica visual em nodes; Make é uma alternativa no-code 100% hospedada. Você precisa de uma só para construir.

A escolha define custo, controle dos dados e teto de complexidade. n8n self-host é barato e flexível; Make é mais rápido de começar mas cobra por operação.

Self-host vs cloud, custo por execução vs por operação, vendor lock-in, código quando precisar (n8n Code node).

Credentials são objetos reutilizáveis que guardam o acesso a um serviço (Gmail, OpenAI, Supabase) uma vez e reusam em todos os nodes.

Centralizar a credencial evita colar a mesma chave em 10 nodes e permite trocar a senha em um lugar só quando vazar.

Credential type, OAuth vs API key, escopo de permissão, conta de serviço dedicada à automação.

Variáveis de ambiente guardam valores fora do código (chaves, URLs, IDs) num arquivo .env ou no painel do serviço.

Separar config de lógica deixa o mesmo fluxo rodar em dev e produção só trocando o ambiente, sem editar nodes.

.env, $env no n8n, nunca commitar segredo, valores por ambiente.

Práticas para que chaves e tokens nunca apareçam em logs, prints, repositórios ou no corpo de respostas de webhook.

Uma chave de LLM vazada vira fatura de milhares de reais em horas. Segredo exposto é o erro mais caro de iniciante.

Rotação de chaves, princípio do menor privilégio, secret manager, mascarar dados em logs.

Um workflow é um grafo: nodes (caixas que fazem algo) ligados por conexões que passam dados em formato de itens JSON.

Entender que tudo é "uma lista de itens fluindo entre nodes" é o modelo mental que destrava todo o resto.

Node, conexão, item, $json, trigger vs ação, fluxo de dados.

Um fluxo mínimo: um Manual Trigger ligado a um node que escreve uma mensagem — sua primeira execução de ponta a ponta.

Provar que o ambiente roda elimina 90% da ansiedade. Você vê dados saindo de um node e entrando no outro.

Manual Trigger, Set/Edit Fields node, executar e ler a saída, painel de execução.

O node que inicia o fluxo: um Webhook reage a uma chamada HTTP; um Schedule Trigger dispara em horários (cron).

O tipo de gatilho define se a automação é reativa (alguém manda dado) ou proativa (roda sozinha de hora em hora).

Webhook URL, método HTTP, Schedule/cron, payload de entrada.

Extrair os campos que importam do item que entrou — corpo do webhook, query string, ou linhas de uma planilha.

A IA só é tão boa quanto o contexto que você dá. Coletar os campos certos é metade da qualidade do resultado.

$json.body, Set node, expressões ={{ }}, validação básica.

Enviar o prompt + dados a um modelo, via node nativo (OpenAI/Anthropic) ou via HTTP Request quando o node não existe.

É o coração da automação com IA. Saber montar o prompt no node e pedir saída estruturada economiza parsing depois.

System vs user prompt, temperature, JSON mode, custo por token.

Transformar a resposta do modelo (texto) em campos estruturados que os próximos nodes conseguem usar.

Sem parsear, a saída é uma string solta. Estruturar permite gravar em colunas, decidir em IFs e mapear campos.

JSON.parse, Code node, structured output parser, fallback se vier mal-formado.

O passo que gera o valor visível: mandar o e-mail, gravar a linha na planilha, inserir o registro no banco.

Sem ação, é só processamento invisível. A ação é o que o cliente percebe e paga por.

Node de saída (Gmail/Sheets/Postgres), mapear campos, confirmar sucesso.

Executar o fluxo de verdade e inspecionar item por item o que entrou e saiu de cada node no painel de execução.

Ler a execução é como você debuga em automação: o erro quase sempre está no formato dos dados entre dois nodes.

Execution log, pin data, re-run com input fixo, inspecionar entrada/saída.

O HTTP Request node fala com qualquer API REST: você escolhe método, URL, headers e body, e recebe a resposta como item.

Quando não existe node nativo, o HTTP Request resolve. Saber usá-lo destrava 100% das integrações.

GET/POST/PUT/DELETE, status code, query params, JSON body.

Como a API prova quem é você: um token no header Authorization: Bearer ... ou um fluxo OAuth com consentimento.

Erro 401 é o tropeço nº1 em integração. Entender Bearer vs OAuth resolve a maioria dos bloqueios.

Bearer token, OAuth2, refresh token, header Authorization.

Persistir dados num banco (Supabase/Postgres): SELECT para ler, INSERT/UPDATE/UPSERT para gravar resultados.

Banco é a memória da automação. Sem ele, cada execução esquece tudo e você não consegue evitar duplicidade.

SELECT/INSERT/UPSERT, chave única, filtro WHERE, Supabase REST.

Usar o Google Sheets como entrada (ler linhas) ou saída (append/update) — o "banco de dados" favorito de quem não é dev.

Cliente entende planilha. Entregar resultado numa aba é a forma mais rápida de mostrar valor sem treinar ninguém.

Append row, update por chave, mapeamento coluna→campo, range.

Processar muitos itens em lotes e buscar páginas de uma API com cursor/offset, em vez de tentar tudo de uma vez.

APIs limitam quantos itens devolvem por chamada e impõem rate limit. Paginar é o que separa protótipo de produção.

SplitInBatches, Loop Over Items, cursor/offset, rate limit, wait.

Usar expressões para transformar e proteger dados: valor padrão quando vem nulo, renomear campos, formatar datas.

Um campo nulo inesperado quebra o fluxo no meio. Tratar nulos é o que torna a automação resiliente a dados sujos.

={{ $json.email ?? 'sem-email' }}, optional chaining ?., default, map.

Capturar falhas em vez de deixar o fluxo morrer em silêncio: error workflow global, ramo de erro do node, continue on fail.

Em produção tudo falha eventualmente. Quem trata erro avisa você; quem não trata descobre pelo cliente irritado.

Error Trigger, continue on fail, Stop and Error, ramo de erro.

Reexecutar um node que falhou por motivo transitório (API instável, timeout) com espera entre as tentativas.

Muita falha é temporária. Um retry com backoff transforma "deu erro" em "resolveu sozinho na 2ª tentativa".

Retry on fail, max tries, wait between tries, timeout, backoff.

Garantir que rodar o mesmo input duas vezes produz o mesmo efeito — não cria dois registros nem manda dois e-mails.

Retries e webhooks reentregam. Sem idempotência, cada reenvio vira duplicata e o cliente recebe a mesma cobrança 3x.

Chave idempotente, UPSERT, dedupe, checar antes de inserir.

Saber o que a automação está fazendo: registrar execuções em log e disparar alerta (Slack/e-mail) quando algo falha.

Você não pode consertar o que não vê. Alerta proativo é a diferença entre 5 minutos e 5 horas de prejuízo.

Log estruturado, alerta no Slack, métrica de sucesso, execution history.

Um ambiente separado (homologação) com dados de teste para validar mudanças antes de mexer na produção.

Testar direto em produção quebra o serviço do cliente ao vivo. Homologação é sua rede de segurança.

Staging vs produção, dados de teste, pin data, smoke test.

Uma lista de verificação final: erros tratados, retries, idempotência, alertas, segredos, e plano de rollback prontos.

O checklist transforma "acho que tá pronto" em "está pronto" — e é o que você mostra ao cliente como garantia.

Go-live checklist, rollback, monitoramento ativo, dono responsável.