🔐 Disponível para clientes com o add-on de Custom Integrations
👤 Para times que precisam de lógica além das peças pré-construídas
🎯 Nível: avançado
As opções pré-construídas do Integrações Pipefy cobrem a maioria dos cenários de integração. Mas toda operação tem casos de borda: uma transformação de dados com regras específicas do negócio, um cálculo que nenhuma opção padrão executa, um formato de arquivo que nenhum helper trata. Nesses momentos, a alternativa sem a opção de Code é abandonar o flow ou construir uma solução técnica fora do Pipefy.
O Code permite executar Node.js ou TypeScript diretamente dentro do flow, com acesso ao ecossistema npm (libs, porém em alguns Single Tenant com restrição de conexão, os pacotes são bloqueados) e aos dados de qualquer passo anterior. A lógica mais específica do negócio passa a viver junto com o processo, no mesmo ambiente que o restante da integração, sem depender de serviços externos para executar código.
📖 O que você vai entender aqui:
Quando usar a peça Code: a pergunta antes da solução
A opção de Code é poderosa e cria uma dependência real: o código precisa ser mantido, entendido e atualizado quando as regras de negócio mudam. Usada no lugar certo, elimina fricção que nenhuma outra opção resolve. Usada no lugar errado, transforma um flow de integração numa aplicação disfarçada que ninguém quer herdar.
Os casos em que Code é a resposta correta têm três características em comum: a lógica é específica demais para existir em um conector padrão, a transformação é repetível e bem definida, e o resultado é um dado ou uma ação que o flow pode usar nos passos seguintes. Quando o código começa a crescer para além de uma função bem delimitada, é sinal de que o problema pode estar no design do flow, não na falta de código.
Antes de escrever código no Code, pergunte: existe uma combinação de opções de utilidade padrão que resolve isso? Um Router com condições encadeadas, um Helper de transformação de texto, uma chamada HTTP com o payload correto? O código só deve entrar quando a resposta for genuinamente não.
Casos de uso de maior retorno
Caso de uso: cálculo financeiro em tempo real e estruturação de card
Em operações que recebem dados de sistemas externos — um ERP, um e-commerce, um motor de cotação ou uma calculadora de pricing — os números raramente chegam prontos. O sistema de origem envia os dados crus (itens, quantidades, valores unitários, alíquotas, descontos), e cabe à automação transformar isso em totais confiáveis antes de registrar a informação. Fazer essa matemática com os operadores nativos de uma ferramenta low-code é arriscado: cálculos monetários em ponto flutuante acumulam erros de centavos (o clássico 0.1 + 0.2 = 0.30000000000000004), e regras como impostos em cascata ou rateios exigem mais expressividade do que um campo de fórmula simples oferece.
Aqui entra nossa opção de Code do Integrações Pipefy. Em vez de espalhar cálculos frágeis por vários nós visuais, você concentra toda a lógica de cálculo em um único bloco de código, apoiado por uma biblioteca especializada que garante precisão e legibilidade. O resultado estruturado alimenta diretamente um novo card no Pipefy, com cada total no seu campo correto, pronto para o fluxo humano de aprovação, auditoria e governança.
Como o fluxo funciona na prática
- Recepção dos dados (Webhook): o sistema externo envia, via webhook, um payload com os dados crus do pedido/cotação — o identificador, o fornecedor e a lista de itens.
- Tratamento e cálculo (Code com mathjs): um único passo de código recebe os itens e executa toda a matemática com a biblioteca mathjs em modo BigNumber (precisão decimal, sem erro de ponto flutuante). Para cada linha calcula valor bruto, desconto, base líquida e imposto; e consolida os totais do pedido: total bruto, total de desconto, base líquida, total de imposto, total geral e ticket médio. Antes de calcular, o código valida que há itens no payload — se vier vazio, falha de forma explícita em vez de gravar lixo.
- Estruturação no Pipefy (Create Card): com os totais já calculados e arredondados, o conector nativo do Pipefy cria um card no pipe de destino, mapeando cada valor para o seu campo estruturado.
- Confirmação síncrona (Return Response): a integração devolve ao sistema externo um JSON com o status, o ID do card criado e os totais consolidados, fechando o ciclo em uma única chamada, sem o sistema de origem precisar consultar nada depois.
Sem a opção de code, o time de TI teria duas opções ruins: ou construir e manter um microsserviço próprio só para fazer essa conta antes de chamar o Pipefy, ou tentar reproduzir a matemática em dezenas de campos de fórmula visual frágeis e difíceis de auditar. Com o Code apoiado por uma biblioteca de cálculo, a regra de negócio fica em um único lugar versionável, testável e preciso, e a plataforma transforma um dado cru de qualquer sistema da empresa, sem código de infraestrutura, em um card governável e auditável dentro do Pipefy.
Boas práticas aplicadas (Code de alta performance)
- Precisão antes de tudo: para valores monetários, configure mathjs com number: 'BigNumber' (ou use decimal.js, mais leve, se precisar só de aritmética decimal). Nunca confie no float nativo para dinheiro.
- Minimize os pacotes: inclua apenas a biblioteca de cálculo essencial. Pacote a mais é "peso" no flow e risco de timeout. Uma lib bem escolhida (mathjs ou decimal.js) cobre a maioria dos casos.
- Lógica de cálculo, não orquestração, dentro do código: o Code Piece deve calcular e devolver dados estruturados — não fazer chamadas HTTP pesadas nem laços gigantes. A criação do card fica no conector nativo do Pipefy, fora do código.
- Valide a entrada: cheque a presença e o formato dos dados (ex.: lista de itens não vazia) no início do código e falhe de forma clara, em vez de gravar um card com totais zerados.
- Idempotência (quando aplicável): se o sistema externo puder reenviar o mesmo pedido, inclua o identificador de origem em um campo de controle e faça uma busca rápida antes de criar, para não duplicar cards em reenvios.
Code tem acesso ao ecossistema npm completo, o que inclui pacotes sem manutenção ativa, com vulnerabilidades conhecidas ou com licenças incompatíveis com uso comercial. Antes de adicionar um pacote, verifique a última atualização, o número de downloads semanais e a licença. Pacotes abandonados viram dívida técnica silenciosa
Governança: o que escalar uso de código exige
O código não exige um desenvolvedor para ser usado, mas exige responsabilidade sobre o código que roda em produção. Em operações enterprise, dois pontos merecem atenção antes de escalar o uso.
A documentação dentro do flow é inegociável. O editor de código suporta comentários, e cada código deve ter pelo menos um comentário explicando o que faz, quais inputs espera e qual estrutura retorna. Um flow sem documentação de código é um flow que ninguém consegue manter quando o autor original não está disponível.
Versionamento e rastreabilidade importam. O Integrações Pipefy versiona os flows publicados, o que significa que mudanças no código são rastreáveis no histórico de versões. Antes de alterar um código em produção, publique como nova versão e mantenha a anterior acessível por pelo menos um ciclo de monitoramento.
Credenciais, tokens e chaves de API nunca devem ser escritos diretamente no código, use variáveis dentro do código para referenciar autenticação. O código fica visível para qualquer usuário com acesso ao flow.
Checklist de conclusão
☐ Quando a opção de Code é a resposta certa e quando indica um problema de design do flow
☐ Por que documentação dentro do código é obrigatória em uso enterprise
☐ Como passar credenciais de forma segura para o código via inputs
☐ O que verificar num pacote npm antes de adicioná-lo a um flow de produção
