Nó Loop

O nó Loop (loop) itera sobre um array e executa os nós filhos conectados uma vez por item. É a forma padrão de processar listas — pedidos, contatos, cards do CRM, linhas de resultado de API — sem duplicar nós no canvas.

Use-o em Automações, na categoria Lógica da paleta.

Figura 1: Nó Loop com array de origem, alias do item e duas saídas

O que faz

Quando o workflow chega a um nó Loop, o engine:

1. Resolve o campo array de origem (suporta {{variables}} e saídas de nós).
2. Faz parse do valor como JSON se for string; valores que não são array são encapsulados em uma lista de um item.
3. Corta o array até o máximo de iterações (padrão 100, limite rígido 500).
4. Para cada item, define variáveis de loop e executa todos os nós conectados à saída A cada item (loop_body).
5. Após todas as iterações, continua pela saída Ao concluir (loop_done).

Dentro do corpo do loop, o item atual fica disponível como:

A saída do nó (em Ao concluir) inclui items (array de valores processados) e count.

Como configurar

Clique duas vezes no nó Loop para abrir o painel de configuração.

Array de origem (obrigatório)

Caminho ou expressão apontando para um array. Exemplos:

{{http_orders.data.orders}}
{{tiny_1.result.data.retorno.contas}}
{{trigger.body.items}}

Se a API retornar um único objeto em vez de array, o engine encapsula em [object] para o loop rodar uma vez.

Se o parse falhar (string JSON inválida), o loop roda zero vezes e segue para Ao concluir com count: 0.

Nome do item (alias)

Nome usado dentro do corpo do loop. Padrão: item.

Escolha um nome curto e significativo quando aninhar loops ou tiver vários arrays no mesmo workflow.

Máximo de iterações

Limite de segurança. Padrão 100; máximo no servidor 500. Itens além do limite são ignorados (não é erro).

Saídas

Conecte Send Text, HTTP, Condição ou qualquer outro nó em A cada item para lógica por linha. Conecte nós de resumo (ex.: notificação ao admin, Variável agregada) em Ao concluir.

Dicas e boas práticas

• Conecte as duas saídas de forma intencional. Nós só em A cada item rodam N vezes; nós só em Ao concluir rodam uma vez no final.
• Normalize os dados antes. Use um nó Variável ou JavaScript antes do loop se a API retornar { data: { items: [...] } } e você precisar de um caminho de array plano.
• Respeite limites de taxa. Combine Loop com Delay dentro do corpo ao enviar mensagens WhatsApp para muitos contatos (veja guias anti-bloqueio).
• Mantenha o corpo enxuto. Lógica pesada em loops grandes aumenta tempo de execução e custo; pré-filtre com Condição ou fatie o array em JavaScript quando possível.
• Depure com o histórico de execução. Cada nó do corpo aparece várias vezes no log (ex.: Send Text (2/15)). Expanda uma execução para verificar input_resolved do item atual.
• Arrays vazios são válidos. O loop pula o corpo e vai direto para Ao concluir — útil para caminhos "sem trabalho" com Condição em count.

Exemplos de uso

Exemplo 1 — Notificar cada fatura vencida (ERP + WhatsApp)

Trigger: Agendamento — dias úteis às 9:00.

Fluxo:

1. Tiny ERP — listar contas vencidas → {{tiny_1.result.data.retorno.contas}}
2. Loop — origem {{tiny_1.result.data.retorno.contas}}, alias conta
3. A cada item → Variável — phone = busca pelo nome do cliente (HTTP ou Tiny "buscar clientes")
4. Condição — {{variables.phone}} não está vazio
5. Send Text — "Olá {{conta.nome_cliente}}, sua fatura {{conta.numero}} de R$ {{conta.valor}} está vencida."
6. Delay — 30s-90s (espaçamento aleatório)
7. Ao concluir → Send Text para o admin — "Concluído: {{loop_1.count}} lembretes enviados."

Exemplo 2 — Etiquetar contatos a partir de lista no webhook

Trigger: Webhook — body POST { "contacts": [{ "phone": "...", "tag": "vip" }] }.

Fluxo:

1. Loop — {{trigger.body.contas}} ou {{trigger.body.contacts}}, alias contact
2. A cada item → Contact — Add tag — phone {{contact.phone}}, tag {{contact.tag}}
3. Ao concluir → Retorno — { "processed": {{loop_1.count}} } para chamadores síncronos do webhook

Exemplo 3 — Processar itens de linha do Shopify

Trigger: Webhook — novo pedido.

Fluxo:

1. Variável — line_items = {{trigger.body.line_items}}
2. Loop — {{variables.line_items}}, alias line
3. A cada item → HTTP — atualizar API interna de estoque com {{line.sku}} e {{line.quantity}}
4. Ao concluir → CRM — Upsert card com total do pedido do trigger

FAQ

Por que meu loop roda 0 vezes?

O array de origem resolveu vazio, JSON inválido ou []. Verifique input_resolved no nó Loop e confirme o caminho do campo da API upstream (muitas vezes .data vs .data.items).

Posso aninhar loops?

Sim. Um loop interno no ramo A cada item do externo funciona; use aliases diferentes (order, line) para evitar sombreamento.

Por que só 100 itens são processados?

O max_iterations padrão é 100. Aumente na config do nó (até 500) se precisar de mais intencionalmente.

O loop executa nós em paralelo?

Não. Os itens são processados sequencialmente — uma passagem completa pelo corpo, depois o próximo item.

O que acontece se um nó dentro do loop falhar?

A execução para com status de erro, a menos que você trate erros upstream. Teste com um array pequeno primeiro.

Posso usar {{input}} dentro do loop?

Sim. {{input.current_item}} e {{input.current_index}} referem-se à iteração atual do loop. Outros campos em input podem ainda refletir a saída do nó anterior conforme a posição no grafo.

Artigos relacionados

• Visão geral de Lógica — todos os nós de Lógica
• Nó Condição — ramificar dentro de loops
• Nó Delay — espaçamento entre iterações
• Variáveis no workflow — {{variables}} e {{input}}
• Como testar e depurar um workflow — inspecionar execuções de loop no histórico