🔐 Requer perfil Super Admin no Pipefy
👤 Para quem vai criar e gerenciar integrações no Integrações Pipefy
🎯 Nível: iniciante-intermediário
Antes de criar a primeira integração no Pipefy Integrations Hub, dois tipos de conhecimento fazem diferença: entender como a plataforma processa flows em escala, e configurar corretamente a Service Account que vai autenticar tudo que interage com a Pipefy. Ignorar um dos dois é a origem da maioria dos problemas que aparecem depois que as integrações já estão em produção.
Este artigo cobre os limites técnicos que definem o comportamento da plataforma sob carga e o modelo de Service Account que separa autenticação de integração de credenciais pessoais. Com esses dois pontos claros, a construção dos flows começa com a base certa.
📖 O que você vai entender aqui:
Como o Pipefy Integrations processa execuções (e os limites que moldam o design dos seus flows)
Entender como a plataforma executa um flow, e dentro de qual envelope de tempo, memória e concorrência ela opera, é o que separa uma integração que escala de uma que quebra em produção.
Como a plataforma processa execuções
Todas as integrações são processadas de forma assíncrona. Quando um flow é acionado, o sistema confirma imediatamente o recebimento e coloca a execução na fila. O processamento acontece em seguida, sem bloquear quem disparou o trigger.
Esse modelo tem uma implicação prática importante: o sistema que disparou o evento não espera o resultado. Para a maioria dos flows, isso é exatamente o comportamento correto. Para flows em que o sistema de origem precisa de uma resposta antes de continuar, como num webhook síncrono, o design da integração precisa considerar isso desde o início.
E aqui entra um limite concreto: o flow tem 30 segundos para reconhecer um gatilho de webhook. Em um cenário síncrono, isso significa que a lógica que precisa devolver resposta ao sistema de origem tem que ser enxuta o suficiente para caber nessa janela. Cálculos pesados, chamadas externas lentas ou grandes manipulações de dados não pertencem ao caminho síncrono, eles devem rodar de forma assíncrona, depois do reconhecimento.
O limite de 50 execuções simultâneas
A plataforma permite até 50 flows rodando ao mesmo tempo por organização. Quando esse limite é atingido, as execuções seguintes entram numa fila de espera e são processadas assim que uma vaga abre. O flow não falha: ele espera. Mas o tempo de espera aumenta proporcionalmente ao volume acima do limite.
Para operações de baixo volume, esse limite nunca aparece. Para operações que disparam integrações em lote, esse limite define o throughput real da integração e precisa estar no radar antes de ir para produção.
A forma mais eficaz de operar dentro do limite de concorrência em processos de alto volume é trabalhar com lotes menores e intervalos controlados entre envios. Em vez de disparar mil execuções de uma vez, enviar em grupos de 40 a 45 mantém o volume abaixo do teto de 50 e evita acúmulo na fila.
Os limites de governança que afetam o design de flows
Além do limite de concorrência, alguns parâmetros técnicos definem o envelope de operação de cada execução individual.
Timeout de 5 minutos por execução
Cada execução de flow tem um tempo máximo de 5 minutos. Se o flow não concluir dentro desse limite, a execução é interrompida. Flows com muitas ações encadeadas, chamadas a APIs lentas ou processamento de grandes volumes de dados em memória são os principais candidatos a atingir esse teto.
O impacto no design é direto: flows longos precisam ser divididos. Sub-flows, loops com lotes menores e chamadas HTTP com timeout configurado adequadamente são as ferramentas para manter cada execução dentro do limite.
512 MB de RAM por execução
Cada execução opera com até 512 MB de memória. Para a maioria dos flows de integração, esse limite nunca é relevante. Ele começa a importar quando o flow carrega arquivos grandes em memória, processa payloads JSON extensos ou usa Code com processamento pesado. Se o flow manipula documentos, imagens ou conjuntos de dados de alta cardinalidade, vale estimar o footprint de memória antes de ir para produção.
Um cuidado específico sobre arquivos: o limite de 10 MB aplica-se SOMENTE à utilidade Files (o files helper). Manipulação de dados via código e o recebimento de arquivos de dados não estão sujeitos a esse limite, mas continuam, sim, sujeitos ao teto de 512 MB de memória da execução. Ou seja: um arquivo pode "entrar" no flow por um caminho que não passa pela utilidade Files, mas se a manipulação dele em memória ultrapassar 512 MB, a execução quebra mesmo assim. A boa prática é nunca carregar o arquivo inteiro em memória, filtrar colunas, processar em lotes e trabalhar por streaming sempre que possível.
Throttling automático entra em ação quando uma única conta gera carga excessiva que afeta a estabilidade da plataforma para os demais usuários. O sistema recusa requisições abusivas sem aviso prévio. Isso é especialmente relevante em migrações em massa ou processos de carga inicial de dados: distribua o volume ao longo do tempo em vez de processar tudo de uma vez.
Em resumo, três decisões de design resolvem a maioria dos problemas com esses limites: fracionar o trabalho (lotes menores, sub-flows) para caber nos 5 minutos e nas 50 execuções simultâneas; manter a memória enxuta (sem carregar arquivos inteiros, processando por lotes) para respeitar os 512 MB; e distribuir o volume no tempo em cargas grandes, para não acionar a fila nem o throttling.
Service Account: autenticação sem credenciais pessoais
Uma Service Account é uma conta de serviço criada especificamente para autenticar integrações. Ela não representa um usuário humano. Tem um e-mail próprio, um Client ID e um Client Secret, e é essa combinação que o Integrações Pipefy usa para se autenticar e operar dentro dos pipes com os quais precisa interagir.
A razão para usar uma Service Account em vez das credenciais de um colaborador é simples: credenciais pessoais têm dono. Quando esse colaborador sai da empresa, muda de função ou tem o acesso revogado, toda integração que usava suas credenciais para de funcionar. Uma Service Account existe independentemente de qualquer pessoa e pode ser gerenciada, auditada e desativada sem impacto em nenhum usuário.
Nomenclatura e permissões: decisões que importam antes de criar
Dois pontos merecem atenção antes de criar a primeira Service Account, porque são difíceis de corrigir depois que as integrações já estão em uso.
Nomenclatura descritiva desde o início. Um nome como "Integração-Onboarding-RH" ou "SA-Financeiro-ERP" comunica propósito, origem e destino. Um nome genérico como "SA1" ou "Teste" vira problema de rastreabilidade em semanas. A descrição também é campo obrigatório de preenchimento real: explique para que essa conta existe, quais sistemas ela conecta e quem é o responsável técnico.
A permissão correta é Pipe Administrator. Esse é o papel que precisa ser atribuído à Service Account em cada pipe com o qual ela vai interagir. Sem essa permissão, a integração não consegue operar dentro do pipe. Esse passo é o mais frequentemente esquecido durante a configuração inicial e é a causa mais comum de flows que disparam mas não executam as ações esperadas.
Checklist de conclusão
☐ O que acontece quando mais de 50 flows tentam executar simultaneamente
☐ Por que o timeout de 5 minutos afeta o design de flows com alto volume de dados
☐ A diferença entre uma Service Account e as credenciais de um usuário Pipefy
☐ Qual permissão a Service Account precisa ter em cada pipe
