Pular para o conteúdo
Guias

Código e APIs nos fluxos: Python, JavaScript e credenciais guardadas

Quando os nós prontos não bastam, os fluxos do CollaborAI Enterprise rodam Python ou JavaScript em ambiente isolado e chamam APIs externas com credenciais cifradas. Veja como usar e os limites de cada um.

Equipe CollaborAI 6 min de leitura
Nó de código em ambiente isolado dentro de um fluxo, ao lado de uma chamada de API com credencial guardada

A maior parte de um fluxo se resolve com nós prontos. Mas sempre aparece o cálculo que nenhum nó faz, ou o sistema que não tem conector. Para esses casos, o módulo Fluxos do CollaborAI Enterprise tem duas saídas: os nós de Código, em Python ou JavaScript, e o nó Requisição HTTP, que fala com qualquer API. Este artigo mostra as duas e as proteções em volta delas.

Ele faz parte da série sobre o módulo, que começa na visão geral.

Os nós de código

São dois, Código Python e Código JavaScript, e funcionam do mesmo jeito: recebem os itens do fluxo, rodam o seu trecho e devolvem itens.

Animação: os itens entram no nó de código, que roda em um ambiente isolado, e saem transformados; a tentativa de acessar a internet a partir do código é bloqueada
O código recebe itens e devolve itens. O ambiente é isolado: sem internet e sem credenciais.

Como o código recebe e devolve dados

  • A variável items traz os itens de entrada. Cada item tem a forma {"json": {...}}.
  • Em Python, o código atribui a result uma lista de dicionários.
  • Em JavaScript, o código é o corpo de uma função e devolve um array com return. Pode usar await.
  • Cada elemento devolvido vira um item de saída.

O nó tem dois modos. Em Uma vez para todos os itens, o código recebe a lista completa. Em Uma vez por item, ele roda separadamente para cada item, que chega na variável item.

O exemplo abaixo recebe números, calcula o quadrado de cada um e marca os pares. Em Python:

result = []
for item in items:
    valor = item["json"]["valor"]
    result.append({
        "valor": valor,
        "quadrado": valor * valor,
        "par": valor % 2 == 0,
    })

E o mesmo em JavaScript:

return items.map((item) => {
  const valor = item.json.valor;
  return { valor, quadrado: valor * valor, par: valor % 2 === 0 };
});

Depois de executar, a tela do nó mostra a entrada, o código e a saída lado a lado:

Detalhes do nó Código Python com o modo Uma vez para todos os itens, o código que calcula quadrados e, à direita, a tabela de saída com seis linhas de valor, quadrado e par
O nó Código Python depois da execução: seis itens entram, seis saem com os campos novos.

No fluxo completo, o código é só um passo. O que vem depois, filtrar, ordenar e limitar, continua sendo nó pronto:

Fluxo executado com oito nós em linha: gatilho manual, separar valores, calcular quadrados em Python, filtrar só os pares, ordenar, limitar aos três primeiros, juntar o resultado e montar a mensagem
Seis valores entram, o código calcula, e os nós prontos filtram, ordenam e ficam com os três maiores.

O que o ambiente isolado significa

O código roda em uma área separada, criada para a execução:

  • Sem internet. O código não chama APIs nem baixa pacotes. Para falar com outro sistema, use o nó Requisição HTTP antes ou depois.
  • Sem credenciais. O código não enxerga as senhas e chaves do fluxo.
  • Só código. O texto {{ }} dentro do código não é interpretado. Os dados chegam por items.
  • Tempo limite. O padrão é 60 segundos por execução do nó.

Quando algo dá errado, a mensagem de erro aponta a linha do seu código.

Quando vale usar código

Use código paraPrefira um nó pronto para
Cálculo com várias regras (comissão, rateio, juros)Criar ou renomear campos
Validar CPF, CNPJ ou formato de arquivoFiltrar, ordenar, limitar
Reorganizar uma estrutura muito aninhadaRemover duplicados, unir listas
Estatística simples sobre a listaFormatar datas

Um fluxo com menos código é mais fácil de manter por quem não programa. E quem não programa pode pedir o trecho no Chat do CollaborAI, descrevendo a entrada e a saída desejada.

O nó Requisição HTTP

É o conector universal: chama qualquer API que responda por https.

  • Método e URL. GET busca, POST envia, PUT e PATCH alteram, DELETE apaga. A URL aceita expressões: https://api.exemplo.com/pedidos/{{ $json.id }}.
  • Corpo. JSON, formulário ou texto puro, o que cobre até serviços antigos em SOAP/XML.
  • Resposta. Lida como JSON, texto ou arquivo. Uma lista na resposta gera um item por elemento.
  • Tempo de espera. 30 segundos por padrão, até 120.

Quatro formas de autenticar

OpçãoQuando usar
Usuário e senha (Basic)Sistemas internos e serviços mais antigos
Token (Bearer)A maioria das APIs modernas
Chave em cabeçalhoAPIs que pedem algo como X-API-Key
Conta conectada (OAuth)APIs do Google e do Microsoft 365, com a sua conta já conectada

Credenciais do fluxo

Senha e chave não são escritas no nó. Elas ficam em Credenciais do fluxo, o ícone de chave na barra superior:

  1. No nó, escolha a forma de autenticação e clique em Nova ao lado do campo de credencial.
  2. Em Credenciais do fluxo, informe o valor. Para token, cole só o valor: o nó acrescenta o Bearer sozinho.
  3. Salve. O valor fica cifrado e não aparece de volta na tela, nem para você.

As credenciais são do fluxo, e não da sua conta. Um fluxo não enxerga a credencial de outro.

As travas de segurança

  • Domínios permitidos. O nó só chama os domínios listados nas Configurações do fluxo. Sem nenhum domínio na lista, não chama nada. Isso impede que um endereço montado por expressão leve os dados para onde não devia.
  • Endereços internos bloqueados. Chamadas para redes privadas são recusadas.
  • Sem redirecionamento. O nó não segue redirecionamentos para outro endereço.

Quando a API falha

Duas opções do nó mudam o que acontece em caso de erro:

  • Tentar novamente, nas configurações do nó, repete a chamada. Erros temporários do servidor são repetidos. Erros como 404, não.
  • Texto de sucesso é um trecho que precisa aparecer na resposta para ela contar como válida. Serve para serviços que respondem “OK” mesmo quando deram erro por dentro.

Código e API juntos

O desenho mais comum combina os dois: Requisição HTTP busca os dados, Código aplica a regra do negócio, e outra Requisição HTTP grava o resultado.

Um exemplo: buscar os pedidos do dia no ERP, calcular a comissão de cada vendedor conforme a faixa de desconto e enviar o fechamento para o sistema de folha. A regra de comissão, que muda a cada trimestre, fica em um único nó de código, fácil de achar e de alterar.


Código e HTTP são as saídas de emergência do módulo: quase tudo se resolve sem eles, mas é bom saber que existem. O próximo artigo da série mostra como testar, acompanhar as execuções e tratar erros.

#fluxos #python #api #enterprise
Compartilhar

Continue lendo

Leve os Fluxos para a sua empresa

O módulo Fluxos faz parte do CollaborAI Enterprise, que roda em ambiente dedicado, com SSO e controle por grupos.

Conhecer o Enterprise