n8n base
Um workflow visual não é apenas uma linha ligando caixas. Cada node recebe dados, aplica uma operação e entrega itens ao próximo, enquanto triggers determinam quando uma execução começa. O caso desta semana é uma integração de pedidos: receber um evento, validar campos, consultar informações por HTTP e separar pedidos válidos de pendências. O desenho será determinístico, preparando a base para acrescentar modelos nas semanas seguintes.
Vamos estudar nodes, credentials, expressions, webhooks, schedules, HTTP Request, branches, loops, error handling e retries como partes de um fluxo único. Não será fornecido um export JSON n8n com versão presumida. Você construirá o workflow no editor da instalação que utilizar e registrará essa versão. O exemplo JavaScript simula o tratamento dos itens e a repetição de eventos, sem afirmar execução do workflow real.
JavaScriptn8nAPIsAo terminar esta aula
- Itens e identidade de operação precisam permanecer rastreáveis entre nodes.
- Credenciais e expressões possuem responsabilidades diferentes.
- Retry e reexecução exigem defesa contra repetição de efeitos.
Antes de continuar: Laboratório: A2A
Nodes transformam itens, não desenhos
FundamentosUm node combina configuração e comportamento. Os dados passam entre nodes como itens, e o fluxo precisa conservar os identificadores usados para ligar respostas às entradas. Se um HTTP Request retorna somente o corpo remoto, verifique como o pedido original será preservado para os passos seguintes. O item atual e os dados de outro node não são necessariamente o mesmo objeto. Uma expressão que parece correta com um único pedido pode falhar quando vários itens atravessam o fluxo. Teste duas entradas diferentes e compare os campos usados em cada saída.
Credentials armazenam a configuração de acesso a serviços e devem ser selecionadas nos nodes apropriados. Não coloque tokens em campos comuns, expressões ou código que será exportado e compartilhado. A credencial deve ser limitada ao serviço e ao ambiente do laboratório. Expressions calculam parâmetros a partir dos dados disponíveis, como o identificador do pedido ou uma URL com parâmetro permitido. Elas não substituem validação: concatenar um destino recebido livremente pode criar requisições a endpoints não autorizados. Prefira base de URL fixa e argumentos validados.
↗ Create and edit credentials↗ Expressions for data transformation
Triggers definem entrada e tempo
FundamentosUm Webhook recebe chamadas externas e inicia uma execução conforme método, caminho e autenticação configurados. URLs e comportamento de teste e produção precisam ser conferidos na instalação; testar no editor não significa que o endpoint de produção está ativo. Defina schema mínimo, limite de payload e resposta HTTP. Uma confirmação de recebimento pode ser diferente da conclusão do processamento. Se o trabalho demora, um identificador de acompanhamento evita manter o cliente aguardando sem saber se o pedido foi aceito.
Schedule Trigger inicia trabalho por tempo. O timezone altera o significado de um horário, especialmente quando o workflow ou a instância possui configuração diferente. Para uma tarefa diária em Cuiaba, registre America/Cuiaba e confira o próximo disparo na instalação. Não teste agendamento somente executando manualmente, pois isso não verifica horário nem ativação. Schedules também podem coincidir com uma execução ainda em andamento. Estabeleça se o trabalho pode sobrepor, se precisa de trava e qual identidade de operação evita processar duas vezes o mesmo período.
HTTP, branches e loops precisam de contratos
FundamentosHTTP Request define método, URL, autenticação, parâmetros e interpretação da resposta. Diferencie erro de conexão, status HTTP de falha e resposta bem formada com erro de domínio. Um corpo200 contendo pedido não encontrado não deve virar consulta bem-sucedida. Valide os campos que o próximo node necessita e preserve origem. Uma chamada de leitura pode receber retry limitado para indisponibilidade transitória; uma chamada de criação exige idempotência ou reconciliação quando o resultado é desconhecido. O tipo de node não decide essa semântica por você.
Branches escolhem caminhos a partir de condições, como pedido válido ou pendente. Escreva condições sobre campos validados, sem depender de uma frase livre. Loops permitem repetir uma etapa ou trabalhar em lotes quando necessário, mas muitos nodes já processam vários itens. Adicionar um loop sem entender esse comportamento pode duplicar chamadas. Um loop explícito precisa de condição de saída e orçamento, e um lote precisa conservar quais itens já foram concluídos. No caso comercial, identificar evento repetido é diferente de ignorar todos os pedidos de um cliente.
const vistos=new Set();
function processar(e) {
if(typeof e.id!=='string'||!Number.isFinite(e.valor)||e.valor<0)return {status:'invalido',id:e.id};
if(vistos.has(e.id))return {status:'duplicado',id:e.id};
vistos.add(e.id);return {status:'aceito',id:e.id,valor:e.valor};
}
console.log([{id:'E1',valor:100},{id:'E1',valor:100},{id:'E2',valor:-1}].map(processar));Falhas e repetição precisam ser observáveis
FundamentosError handling pode direcionar tratamento de falhas e um workflow de erro conforme a configuração do n8n. Não converta todas as falhas em item vazio: isso deixa o fluxo parecer concluído sem mostrar a pendência. Retrying um node é diferente de reexecutar todo o workflow, e cada estratégia pode repetir passos anteriores. O registro de execução precisa indicar qual node falhou, argumentos relevantes, tentativa e operação. Minimize dados pessoais e configure retenção adequada; guardar todas as entradas indefinidamente também possui custo e risco.
O simulador valida id e valor, usa um Set para reconhecer evento repetido e produz aceito, invalido ou duplicado. Essa defesa vive somente no processo. Na integração, um armazenamento durável com unicidade deve guardar a identidade do evento ou operação, de forma segura sob concorrência. Avalie dois itens válidos, um inválido, duplicado, resposta HTTP malformada e indisponibilidade transitória. O sucesso do workflow inclui encaminhar pendências corretamente, não apenas manter os nodes verdes no caso nominal.
Exercício aplicado
Receba eventos E1/E2, consulte dados por HTTP e encaminhe entradas inválidas para pendência. O mesmo evento pode chegar duas vezes e o agendamento diário não deve repetir o trabalho do período sem controle.
- Execute o validador local com nominal, inválido e duplicado.
- Monte o fluxo na versão instalada e acompanhe dois itens distintos.
- Teste Webhook e timezone do Schedule com evidências próprias.
- Injete falha HTTP e documente tratamento, retry e deduplicação.
Abrir resolução comentada
O primeiro evento E1 é aceito, sua repetição é marcada duplicada e E2 com valor negativo é inválido. O validador verifica o conteúdo antes de inserir o identificador no registro, permitindo que uma entrada inválida corrigida seja processada depois conforme a política. A ordem de validação e deduplicação precisa ser deliberada no sistema real.
O workflow n8n deve reproduzir esses caminhos usando trigger, transformação, condição e armazenamento escolhido. O código não oferece export compatível nem executa HTTP. Para afirmar a integração, capture dados de entrada e saída dos nodes e o histórico de erro e retry na versão realmente instalada.
const vistos=new Set();
function processar(e) {
if(typeof e.id!=='string'||!Number.isFinite(e.valor)||e.valor<0)return {status:'invalido',id:e.id};
if(vistos.has(e.id))return {status:'duplicado',id:e.id};
vistos.add(e.id);return {status:'aceito',id:e.id,valor:e.valor};
}
console.log([{id:'E1',valor:100},{id:'E1',valor:100},{id:'E2',valor:-1}].map(processar));Como conferir seu resultado
- Dados de E1 e E2 não se misturam.
- Entrada inválida termina com motivo explícito.
- Repetição não gera outro efeito e falhas são observáveis.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Entender itens/expressões/triggers.
- Separar correlação e execução do workflow.
Webhook recebe dois pedidos, expressão sempre usa primeiro. Schedule diário America/Cuiaba e retry repetem E9. Diagnostique.
Conferir raciocínio e critérios de domínio
A expressão que usa o primeiro item aplica os dados do pedido 1 ao pedido 2; isso é erro de associação, mesmo que o primeiro resultado pareça correto.
O disparo diário deve usar America/Cuiaba e identidade do período. Uma execução manual não demonstra disponibilidade do Webhook nem do agendamento.
Retry de E9 mantém a mesma intenção comercial, embora executionId mude. O ledger impede repetir efeito concluído; execução nova não é pedido novo.
Evidências para autoavaliação ou revisão por pares
- Itens: A expressão que usa o primeiro item aplica os dados do pedido 1 ao pedido 2; isso é erro de associação, mesmo que o primeiro resultado pareça correto.
- Tempo: O disparo diário deve usar America/Cuiaba e identidade do período. Uma execução manual não demonstra disponibilidade do Webhook nem do agendamento.
- Repetição: Retry de E9 mantém a mesma intenção comercial, embora executionId mude. O ledger impede repetir efeito concluído; execução nova não é pedido novo.
Um erro frequente
Execution Id novo significa efeito comercial novo.
Tentativas têm executionIds diferentes, mas compartilham intenção comercial.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Um loop é necessário para todo conjunto de itens?
Não. Muitos nodes já processam os itens recebidos.
Verifique o comportamento para evitar chamadas duplicadas.
2. Executar manualmente prova o Schedule?
Não. É necessário conferir horário, timezone e ativação.
O trigger temporal é uma condição diferente da execução manual.
3. Retry de node e reexecutar workflow são iguais?
Não. Podem repetir etapas diferentes.
A identidade de operação deve proteger efeitos em ambos os casos.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Work with nodes
n8n • consulta: 2026-10-06
n8nTipos de nó, configuração, Retry On Fail e comportamento de erro.
Limites: Retries exigem limites e idempotência; Always Output Data em IF pode causar loop infinito.
- Create and edit credentials
n8n • consulta: 2026-10-06
n8nConfigurar credenciais para autenticar integrações.
Limites: Requer contas dos serviços; limitar permissões e proteger exportação/configuração.
- Expressions for data transformation
n8n • consulta: 2026-10-06
n8nExpressões, dados dinâmicos e transformações.
Limites: Validar valores ausentes e tipos; expressões não são prompts de agente.
- Webhook
n8n • consulta: 2026-10-06
n8nAPIsURLs de teste/produção, métodos, autenticação e resposta de webhook.
Limites: Exposição pública requer autenticação apropriada; revisar correlação e duplicidade de eventos.
- Schedule Trigger
n8n • consulta: 2026-10-06
n8nIntervalos/cron e timezone em workflows agendados.
Limites: Workflow precisa de publicação/ativação conforme versão; timezone deve ser explícito.
- HTTP Request
n8n • consulta: 2026-10-06
n8nMétodos, URLs, auth, body, paginação e tratamento da resposta HTTP.
Limites: Rate limits, timeouts e idempotência dependem também da API chamada.
- Split with conditionals
n8n • consulta: 2026-10-06
n8nIf e Switch para rotas determinísticas.
Limites: Testar ausência de dados e todos os ramos.
- Loop
n8n • consulta: 2026-10-06
n8nIteração implícita por item e loops explícitos.
Limites: Limitar iterações e evitar reprocessamento infinito.
- Handle errors gracefully
n8n • consulta: 2026-10-06
n8nError workflow, Error Trigger e Stop and Error.
Limites: Erros de trigger têm payload diferente; dados de execução dependem da persistência configurada.
- View all executions
n8n • consulta: 2026-10-06
n8nInspecionar runs, estado, histórico e retentativas.
Limites: Disponibilidade de dados depende de configurações de salvamento e edição/licença.