Gatilhos

Todo fluxo começa por um gatilho — o nó que define quando ele roda e que produz os primeiros items. Escolha o gatilho conforme o que dá a partida: uma pessoa clicando, um horário, um chamado de outro sistema ou um dado que apareceu.

Mais de um ponto de partida

Um fluxo pode ter mais de um gatilho — por exemplo, um agendamento para a rotina diária e um webhook para quando outro sistema precisar antecipá-la, os dois ligados aos mesmos passos.

Cada execução parte de um gatilho só: o que realmente disparou. O webhook parte do webhook, o agendamento parte do agendamento — os demais ficam parados naquela execução, e os passos seguintes rodam uma vez, com os itens de quem deu a partida.

Quando você manda executar na hora e o fluxo tem mais de um ponto de partida, o sistema pergunta Por onde começar? e você escolhe qual usar naquela execução. Com um gatilho só, não há o que perguntar e a execução segue direto.

Disparo manual

Inicia o fluxo sob demanda: pelo botão Executar agora da lista de fluxos, por Executar fluxo no editor ou por chamada de API. Ideal para rotinas que você dispara quando quer, e para montar e testar um fluxo novo.

O que você mandar no disparo vira o primeiro item. Se enviar uma lista no campo items, cada elemento dela vira um item — vale também para o Webhook, a Ferramenta MCP, a Ferramenta de IA e o Evento LBHM.

Agendamento

Dispara na hora que você marcar. São duas escolhas independentes: quando começa e como se repete.

O fluxo precisa estar ativo para o agendamento valer. Na repetição semanal, marque ao menos um dia; em "Executar em", informe a data e a hora — sem isso o fluxo fica sem próximo disparo até você completar.

Os gatilhos TOTVS RM (polling), Data Lake (linhas novas) e Dimep — Novas marcações usam este mesmo controle de agendamento.

Webhook

Inicia o fluxo quando recebe um chamado externo (uma requisição HTTP) num endereço próprio, no formato https://<sua-instância>/webhook/<endereço>. Serve para integrar outro sistema: quando algo acontece lá, ele avisa o NEXUS Flow e o fluxo roda.

O endereço já vem pronto quando você acrescenta o nó — não precisa inventar um. Para trocá-lo, apague o campo e salve: a plataforma gera outro na hora. Se preferir escrever o seu, use de 12 a 128 letras, números, _ ou -; o editor avisa se outro fluxo já estiver usando aquele endereço, em vez de deixar os dois disputarem a mesma URL.

O corpo recebido vira o item inicial. Se o corpo não for JSON, ele chega no campo body; se não houver corpo, valem os parâmetros da URL.

Quem pode chamar este endereço

Cada gatilho de webhook decide isso na caixa Qualquer um pode chamar esta URL:

Prefira deixar fechado. Com o endereço aberto, quem chegar à URL dispara o seu fluxo — e ela circula mais do que parece: fica no histórico do navegador de quem testou, no print do editor, no registro do sistema que chama. Fechado, a URL vira só um endereço: sem a chave, a chamada é recusada. E, como cada consumidor tem a chave dele, você sabe quem chamou, corta um sem parar os outros e dá a cada um o ritmo que ele merece.

Deixe aberto quando quem chama não consegue apresentar uma chave — o formulário de um site, um serviço que só aceita colar uma URL, um aviso automático de outra plataforma. Aí escolha um número de chamadas por minuto próximo do movimento esperado: é a proteção que resta, e ela evita que uma repetição descontrolada lá fora consuma a capacidade da sua instância.

Para fechar um webhook que hoje está aberto, siga esta ordem: primeiro autorize os apps que devem dispará-lo, depois desmarque a caixa. Assim a integração não para em nenhum momento.

Autorizando um app

Com a URL fechada, o painel Apps com acesso, logo abaixo do endereço no editor, mostra quem pode disparar. Escolha o app na lista, informe quantas chamadas por minuto ele pode fazer aqui e confirme no ＋; o × de cada linha tira o acesso. Vale na hora, sem precisar salvar o fluxo de novo.

Num nó recém-criado o painel pede que você salve o fluxo antes — o endereço ainda não existe para ser autorizado. E, se a URL estiver fechada sem nenhum app na lista, o painel avisa: ninguém consegue disparar o fluxo por ela.

O mesmo app pode ter 60 chamadas por minuto num webhook e 120 em outro — o teto é do app naquele webhook. Num endereço aberto esse número não é usado: lá vale o teto do gatilho, igual para todos. Autorizar um app num endereço aberto continua valendo a pena para reconhecê-lo no histórico de chamadas.

Cadastrar os apps, emitir e revogar chaves é assunto de Apps.

Chamando o webhook

A chave vai no cabeçalho Authorization, nunca na URL — endereço aparece em registro de acesso, em histórico e em mensagem de erro; chave, não:

POST /webhook/8f3c2b1a9d7e4f60
Host: sua-instância.nexusflow.lbhm.com.br
Authorization: Bearer nxa_1a2b3c4d.<o restante da chave>
Content-Type: application/json

{ "pedido": 98213 }

A resposta sai na hora, com o número da execução — o fluxo roda em seguida, então quem chamou não recebe o resultado dele:

Toda chamada fica registrada, inclusive as recusadas e o motivo, no histórico do app. É o primeiro lugar a olhar quando um consumidor diz que "não está disparando".

Se o sistema de origem puder repetir a mesma chamada, envie o cabeçalho Idempotency-Key com um identificador seu. Dentro de 24 horas, uma repetição com a mesma chave devolve a execução original em vez de rodar de novo:

POST /webhook/8f3c2b1a9d7e4f60
Content-Type: application/json
Idempotency-Key: pedido-98213

{ "pedido": 98213 }

Ferramenta MCP

Publica o fluxo como uma ferramenta que um assistente de IA pode chamar. Use quando quiser que alguém peça a automação em linguagem natural, em vez de abrir o editor.

O fluxo precisa estar ativo para a ferramenta aparecer e ser chamada. O assistente recebe a saída dos nós finais do fluxo. Se a execução demorar mais que o tempo de espera, ele recebe o número da execução e busca o resultado depois, pela ferramenta nexusflow_resultado.

Para conectar o assistente, aponte-o para o endereço /mcp da sua instância, com o token dedicado às ferramentas. Fale com a LBHM para obtê-lo.

Ferramenta de IA

Publica o fluxo como ferramenta de um agente de IA da própria plataforma. Enquanto a Ferramenta MCP abre o fluxo para um assistente de fora, aqui quem o chama é um agente que você montou aqui dentro.

Os argumentos escolhidos pelo agente viram o primeiro item, como no Disparo manual.

Escolha o que volta ao agente com o nó Devolver ao agente: nele você recorta os campos que interessam ou escreve uma frase pronta por registro. Sem esse nó, volta a saída do último nó que rodou — o que num fluxo com ramificações depende de qual ramo terminou por último, e muda sem aviso quando você mexe no desenho.

TOTVS RM (polling)

Executa uma consulta no seu RM no intervalo configurado e emite cada linha do resultado como um item. Você informa a credencial do RM, o código da sentença, a coligada, o sistema e os parâmetros.

Este gatilho não lembra o que já leu: a cada disparo ele roda a sentença inteira de novo e reemite todas as linhas devolvidas. Se a sentença trouxer sempre o mesmo conjunto, os mesmos registros são processados a cada rodada — em duplicidade.

A saída é escrever a sentença de forma que ela devolva só o que ainda falta e fazer o fluxo marcar o registro no fim:

SELECT ID, VALOR
  FROM MEUS_REGISTROS
 WHERE PROCESSADO = 0

ou, quando houver data de alteração, filtre por ela (WHERE DATAALTERACAO > :ULTIMA_N) e mantenha a marca atualizada. Deixe também o destino preparado para receber o mesmo registro duas vezes (atualizar em vez de duplicar).

Para varrer resultados grandes, ligue Paginar resultados e informe os parâmetros de página e de limite da sua sentença, o tamanho da página e a página inicial.

Data Lake (linhas novas)

Verifica um dataset do Data Lake no intervalo configurado e dispara apenas com as linhas que apareceram desde a última execução bem-sucedida — ele lembra onde parou. É a forma de um fluxo consumir o que outro fluxo gravou, cada um no seu ritmo.

Informe o Dataset e, se quiser, o Máx. de linhas por disparo.

Quando uma execução falha, ele não avança a marca de leitura: as mesmas linhas voltam na rodada seguinte, para você corrigir e reprocessar. Por isso, deixe o fluxo preparado para receber a mesma linha duas vezes — por exemplo, gravando por uma chave que identifique a linha, o que atualiza a que já existe, em vez de simplesmente acrescentar.

Dimep — Novas marcações

Consulta as marcações de acesso do Dimep no intervalo configurado (padrão a cada 5 minutos) e emite só as novas desde a última execução bem-sucedida, uma marcação por item, na ordem em que aconteceram. Usa uma credencial do Dimep; deixe Catraca (Pointer) em branco para acompanhar todas, e use Máx. de marcações por disparo para limitar o volume de cada rodada (padrão 500).

Na primeira execução ele não traz histórico: fixa o ponto de partida no momento atual e passa a emitir o que vier daí em diante. Como no Data Lake, uma execução que falha não avança a marca — as mesmas marcações voltam na rodada seguinte, então deixe o que vem depois preparado para receber a mesma marcação duas vezes (gravando com uma chave que a identifique, em vez de somar cegamente). Veja os demais nós em Dimep.

Erro (Error Trigger)

Dispara quando qualquer outro fluxo falha, recebendo as informações do erro como item — qual fluxo, qual execução e a mensagem. Serve para tratar a falha do seu jeito: avisar no Teams, abrir um chamado, reprocessar o registro.

Para simplesmente receber um e-mail quando um fluxo falhar, não é preciso montar fluxo nenhum: ligue o aviso em Configurações, que agrupa num único e-mail tudo o que falhou no intervalo. Use este gatilho quando a reação for mais do que avisar.

Evento LBHM

Dispara quando algo acontece em outro sistema da suíte LBHM. Escolha a Aplicação, a Entidade e o Evento que interessam; deixe qualquer nível em branco para aceitar tudo daquele nível. O fluxo roda com os dados do acontecimento como item, mais um campo __evento com a origem.

A suíte publica o evento Tasks → Tarefa → Criada, vindo do LBHM Tasks. A lista de opções cresce conforme os sistemas passam a publicar novos eventos.

Diferente do Webhook, aqui o sistema de origem não precisa conhecer o seu fluxo: quem decide o que escutar é o próprio fluxo. Vários fluxos podem escutar o mesmo evento — cada um roda a sua execução. O fluxo precisa estar ativo para ser disparado.

Depois do gatilho, os nós de dados e lógica e os nós de ação fazem o trabalho.