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.
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.
Como o código recebe e devolve dados
- A variável
itemstraz os itens de entrada. Cada item tem a forma{"json": {...}}. - Em Python, o código atribui a
resultuma lista de dicionários. - Em JavaScript, o código é o corpo de uma função e devolve um array com
return. Pode usarawait. - 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:
No fluxo completo, o código é só um passo. O que vem depois, filtrar, ordenar e limitar, continua sendo nó pronto:
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 poritems. - 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 para | Prefira um nó pronto para |
|---|---|
| Cálculo com várias regras (comissão, rateio, juros) | Criar ou renomear campos |
| Validar CPF, CNPJ ou formato de arquivo | Filtrar, ordenar, limitar |
| Reorganizar uma estrutura muito aninhada | Remover duplicados, unir listas |
| Estatística simples sobre a lista | Formatar 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ção | Quando usar |
|---|---|
| Usuário e senha (Basic) | Sistemas internos e serviços mais antigos |
| Token (Bearer) | A maioria das APIs modernas |
| Chave em cabeçalho | APIs 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:
- No nó, escolha a forma de autenticação e clique em Nova ao lado do campo de credencial.
- Em Credenciais do fluxo, informe o valor. Para token, cole só o valor: o nó acrescenta o
Bearersozinho. - 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.