Ações

Os nós de ação fazem algo acontecer a cada item: chamam uma API, consultam ou gravam num banco, enviam um e-mail, geram arquivos, falam com outros sistemas. Vários usam uma credencial.

HTTP Request

Chama uma API HTTP (GET, POST, PUT, PATCH, DELETE ou HEAD) por item. Informe a URL (que pode usar {{ … }} com dados do item), os cabeçalhos — um por linha, no formato Nome: valor — e, nos métodos com corpo, o conteúdo a enviar. A autenticação é opcional e vem de uma credencial. O HEAD traz só o código e os cabeçalhos da resposta, sem o conteúdo: use-o para conferir se um endereço responde sem baixá-lo.

Redirecionamentos

Por padrão, o nó não segue redirecionamentos: uma resposta 3xx chega como está, com o código e o cabeçalho de destino. Marque Seguir redirecionamentos para o nó ir até o endereço final, até o Máximo de redirecionamentos (5 por padrão, até 10); passando disso, o item volta com erro. Com a opção marcada, o item traz também url_final (onde a chamada chegou) e redirecionamentos (quantos saltos houve).

Depois de um redirecionamento 301, 302 ou 303, a chamada seguinte é feita como GET, sem corpo. A autenticação só acompanha a chamada enquanto ela continua no mesmo servidor — mesmo protocolo, domínio e porta.

Endereços da rede interna

O nó recusa endereços da rede interna, tanto no endereço informado quanto em cada redirecionamento. Se o endereço resolver para um IP privado, de loopback ou de link local, a chamada não é feita e a recusa segue o Em caso de erro da aba Config, como qualquer falha de comunicação. Use o endereço público do serviço; para bancos e sistemas que só existem dentro da rede do cliente, use o agente local.

Ao seguir redirecionamentos, os cabeçalhos que você escreveu também ficam para trás quando o endereço muda de servidor — só Accept, Accept-Language, User-Agent e Content-Type acompanham. E um redirecionamento 307 ou 308 que peça para reenviar o corpo a outro servidor não é seguido: o nó não reenvia os dados e o item volta com erro.

O que vem de volta

O campo O que vem de volta decide como a resposta chega ao item:

• Texto ou JSON (padrão) — o corpo vem no campo body, já entendido como JSON quando o serviço responde em JSON.
• Um arquivo (PDF, planilha, imagem…) — o corpo vira um arquivo anexado ao item, em vez de texto. É o que permite baixar um PDF ou uma planilha de uma API e mandá-lo como anexo do Enviar e-mail, ou entregá-lo ao Google Drive.

Escolhendo arquivo, aparecem mais dois campos: Propriedade binária de saída — o nome pelo qual os próximos nós encontram o arquivo, data por padrão — e Nome do arquivo. Deixe o nome em branco para usar o que o servidor informar; se ele não informar, o nó usa o final da URL.

Ritmo das chamadas

Muitas APIs limitam quantas chamadas aceitam por período e recusam o excesso. Na aba Config você diz esse limite ao nó, no mesmo formato em que a API o publica:

O limite vale para o nó inteiro, não para cada item: com 100 a cada minuto, um lote de mil itens sai espaçado, respeitando a conta.

Ainda na aba Config, Repetir quando a API recusar por excesso de chamadas trata o caso em que a recusa acontece mesmo assim. Ligada, o nó espera o tempo que a própria API pedir — no máximo um minuto por tentativa — e chama de novo, até o número de Tentativas (3 por padrão, no máximo 10). Se a API não disser quanto esperar, a espera vai dobrando a cada tentativa. Esgotadas as tentativas e a recusa continuando, o item sai marcado como erro, com o aviso de reduzir o máximo de chamadas do nó.

A opção vem desligada: sem ela, a recusa chega como um item comum, com o código da resposta, e o fluxo segue como se a chamada tivesse acontecido — o que é o comportamento que os fluxos já montados esperam.

Uma resposta com código de erro (4xx, 5xx) não interrompe o fluxo: ela chega normalmente, com o status e o corpo, para você decidir o que fazer com um IF. Já uma falha de comunicação (servidor fora do ar, nome não resolvido, tempo esgotado) é uma falha do nó e segue o Em caso de erro da aba Config — que, por padrão, encerra a execução. Veja Ajustes do nó. Para interromper de propósito, use Marcar erro.

Rastrear site

Percorre as páginas de um site público a partir de um endereço e devolve um item por página visitada. Serve para diagnosticar um site: links quebrados, imagens pesadas, formulários e os textos que cada página mostra.

Informe o Endereço do site — pode vir sem https://, como www.exemplo.com.br. O nó começa por ele e segue os links do próprio site até a Profundidade escolhida (quantos cliques a partir da página inicial, 2 por padrão) e até o Máximo de páginas (30 por padrão, até 200). Se o endereço redirecionar, de http para https ou para o www, o site passa a ser o endereço final.

Cada item traz os campos do item de entrada e mais:

Cada link e cada imagem são conferidos uma vez só, mesmo que apareçam em várias páginas, até o Máximo de links e de imagens verificados (300 por padrão). Links para outros sites também são conferidos, mas não visitados.

Para não sobrecarregar o site visitado, o nó espera entre uma requisição e outra (Espera entre requisições ao site, 500 ms por padrão) e respeita o robots.txt do site — desmarque Respeitar o robots.txt do site apenas num site seu. Por isso, cada site leva alguns minutos, e a análise de um site para em 15 minutos: o que faltar não entra no resultado. Para analisar vários, ponha o nó num sub-fluxo e chame-o com Executar fluxo, uma execução por site. Os campos da página (url, status, titulo, texto…) substituem os de mesmo nome do item de entrada.

Duas coisas o nó não enxerga:

• Conteúdo montado por JavaScript depois que a página carrega. Um formulário embutido por script aparece em formularios_terceiros, mas os campos dele não são contados.
• Endereços da rede interna, como no HTTP Request: o endereço inicial, os links e os redirecionamentos que apontam para dentro são recusados.

Para montar um relatório, use Separar lista num campo de lista (links_quebrados, imagens_pesadas) e Agregar para juntar as linhas. Ao levar para o HTML um texto que veio do site, passe-o pela função escapeHtml(), que troca <, >, & e aspas pelas entidades correspondentes.

Banco SQL

Executa um comando SQL num banco externo, usando uma credencial de banco — na credencial você escolhe o banco: MySQL/MariaDB, PostgreSQL ou SQL Server. Não é só consulta: um SELECT devolve uma linha por item para os próximos passos, e um comando de escrita (INSERT, UPDATE, DELETE) devolve a quantidade de linhas afetadas.

Os {{ … }} na consulta

Vale para os quatro nós de banco desta página — Banco SQL, SQL Server, Oracle e Banco local (via agente).

Num valor, escreva o {{ … }} onde o valor entra, com as aspas normais. O nó envia o conteúdo do item separado da consulta, e é isso que impede um texto vindo de fora — o corpo de uma chamada externa, um campo digitado pelo cliente — de virar comando no seu banco:

SELECT * FROM clientes WHERE id = {{ $json.id }}
SELECT * FROM clientes WHERE nome LIKE '%{{ $json.termo }}%' AND uf IN ({{ $json.ufs }})

Nome de tabela ou de coluna é outra coisa: nessa posição banco nenhum aceita um valor. Quando o nome vem do item, escreva-o com cerquilha — {{# … }}:

SELECT * FROM {{# $json.tabela }} ORDER BY {{# $json.coluna }}

O nome pode ter letras, números e _ $ #, em até três partes separadas por ponto (base.esquema.tabela); qualquer outra coisa é recusada. Nome fixo continua escrito direto na consulta, sem chaves.

Um {{ … }} comum logo depois de FROM, JOIN, INTO, UPDATE, ORDER BY ou GROUP BY é recusado, com o aviso de trocar pela forma com cerquilha — antes o banco devolvia um erro sem pista, ou pior, ORDER BY simplesmente ordenava errado sem reclamar. Consultas que só usam {{ … }} em valores seguem como estavam.

Cada execução leva um comando só: SELECT …; DELETE … no mesmo campo é recusado antes de chegar ao banco.

SQL Server

Mesmo comportamento do Banco SQL, com uma credencial própria de SQL Server — use este nó quando precisar dos ajustes específicos dela: se confia no certificado do servidor (o padrão, útil em rede interna com certificado próprio) e se exige criptografia na conexão.

Oracle

Mesmo comportamento, com uma credencial de Oracle. Na credencial, identifique o banco por Service Name (recomendado) ou por SID. No Oracle, escreva a sentença sem o ponto e vírgula final.

Banco local (via agente)

Consulta um banco que não está publicado na internet — um arquivo Access (.mdb/.accdb), por exemplo — através de um agente instalado na rede onde o banco vive. Escolha o Agente local, a Conexão e escreva o SQL; o resultado volta como items, igual aos demais nós de banco. Ajuste o Timeout ao tempo que a consulta costuma levar: esgotado o prazo, o nó falha avisando que o agente não respondeu. Veja Agente local para instalar e registrar.

Enviar e-mail

Envia um e-mail por item, em texto ou HTML, usando uma credencial SMTP. Além do destinatário, aceita CC, BCC, nome do remetente e Reply-To — todos com {{ … }}, e cada campo aceita vários endereços separados por vírgula ou ponto e vírgula.

Em Anexos — propriedades binárias você informa quais arquivos do item seguem junto (data é o nome padrão). É assim que o PDF do RM — Gerar Relatório ou a saída do Salvar em arquivo viram anexo. Separe por vírgula para mandar mais de um.

Enviar e-mail (modelo)

Envia um e-mail a partir de um modelo já cadastrado, em vez de digitar o texto no nó. Escolha o Modelo e preencha as variáveis que ele pede — cada valor aceita {{ … }} com dados do item. O assunto e o corpo vêm do modelo; aqui você define só destinatários, CC, BCC, nome do remetente e Reply-To. Use quando o mesmo texto se repete em vários fluxos e você quer mantê-lo num lugar só — veja Modelos de e-mail para escrever e manter o texto.

Salvar em arquivo

Transforma o conteúdo de uma variável do item num arquivo que segue anexado ao item, pronto para ser enviado por e-mail ou entregue ao Google Drive.

Sobre os formatos: no Texto, uma lista sai com uma linha por item. No CSV, uma lista de registros vira tabela — as colunas são todos os campos que aparecem, mesmo os que só existem em alguns registros, para nenhum dado se perder no caminho.

O arquivo trafega junto com o item durante a execução; ele não fica guardado no sistema depois.

Ler CSV

Lê um CSV e transforma cada linha num item.

Se o arquivo vier vazio ou faltar no item, a linha segue marcada com o motivo e o restante do lote continua.

Ao subir o arquivo pelo próprio nó, ele passa a fazer parte do fluxo e é carregado a cada execução — bom para tabelas de referência pequenas. Para arquivos grandes, baixe por HTTP ou pelo agente e leia pela variável binária.

Como os arquivos circulam entre os nós

Arquivo, aqui, é algo que viaja junto com o item sob um nome — data, por padrão. Quem produz arquivo (Salvar em arquivo, RM — Gerar Relatório, HTTP Request com o retorno em arquivo, Google Drive — Arquivos ao baixar) grava sob esse nome; quem consome (Ler CSV, Enviar e-mail, Google Drive — Arquivos ao enviar) pergunta por ele. Se um passo já anexou algo, o seguinte pode usar outro nome e os dois convivem no mesmo item.

Um caminho completo, de ponta a ponta:

RM — Consulta SQL  →  Salvar em arquivo (JSON, "relatorio")  →  Enviar e-mail (anexos: relatorio)
Google Drive — Arquivos (baixar)  →  Ler CSV  →  Editar campos  →  Banco SQL
HTTP Request (retorno em arquivo)  →  Enviar e-mail (anexos: data)

Marcar erro

Encerra a execução em erro, com a mensagem que você escrever. Use quando uma condição torna o restante do fluxo inválido e você quer que a execução conste como falha (visível no Monitor e capturável por um gatilho de Erro).

Google Drive

Dois nós — Google Drive — Arquivos e Google Drive — Compartilhamento — cuidam de listar, baixar, enviar e compartilhar arquivos. Veja Google Drive.

Controle de acesso Dimep

Há nós dedicados para ler as marcações das catracas e para manter pessoas, credenciais, visitantes, visitas e veículos. Veja Dimep.

Outros sistemas LBHM

Os nós Tasks (criar, atualizar, listar, consultar e tópicos), Utils (consultar e buscar CEP) e LIP (notificar) conversam com os demais sistemas LBHM. Veja Integrações LBHM.

Para falar especificamente com o TOTVS RM, veja os nós do TOTVS RM.