🔐 Disponível para clientes com o add-on de Custom Integrations
👤 Para quem está construindo o primeiro flow ou revisando flows existentes
🎯 Nível: iniciante-intermediário
Um flow publicado sem testes adequados é uma questão de quando vai falhar, não se. O problema mais frequente não está na escolha do trigger ou na configuração das ações: está no ciclo de desenvolvimento. Flows construídos de uma vez e testados só no final chegam à produção com mapeamentos quebrados, dados ausentes não tratados e caminhos condicionais que nunca foram verificados.
Use AI com os artigos, para lhe sugerir ideias de modelagem, que sigam boas práticas e respeitem os limites do produto.
Este artigo cobre os quatro elementos que compõem qualquer flow no Integrações Pipefy, os três tipos de trigger e quando cada um faz sentido, e o ciclo de testes que separa um flow confiável de um flow que funciona na primeira vez mas falha no segundo.
📖 O que você vai entender aqui:
Os elementos essenciais de um flow
Todo flow de integração é composto pelos mesmos blocos, independente da complexidade da integração.
O Trigger é o ponto de entrada: define o evento que inicia a execução. Sem trigger, o flow não roda. Steps são os blocos individuais de construção: cada step é um conector que realiza uma ação específica ou se comunica com um serviço externo. Actions são as operações concretas que cada step executa: criar um registro, enviar um e-mail, atualizar um campo. O Router divide o flow em caminhos diferentes com base em condições: se um dado existe, se um valor está acima de um limite, se um campo tem determinado conteúdo.
Esses quatro elementos se combinam em qualquer ordem e profundidade, mas a lógica é sempre a mesma: o trigger inicia, os steps executam ações, o Router decide qual caminho seguir. Entender o papel de cada um antes de começar a construir evita retrabalho na estruturação do flow.
Na hora de montar os steps, existe uma regra que poupa tempo, memória e dor de cabeça de manutenção: antes de escrever código, verifique se uma alguma opção nativa da aba Utility resolve o problema. As opções nativas são mais rápidas, mais eficientes em consumo de recursos e muito mais fáceis de ler e auditar do que um bloco de código personalizado. Ir direto para o Code costuma ser o caminho mais trabalhoso e mais frágil.
A aba Utility do flow builder concentra um repertório que cobre a grande maioria dos casos de tratamento de dados, sem uma linha de código:
- CSV — converter CSV para JSON, JSON para CSV e Excel (.xlsx/.xls) para CSV.
- Files Helper — ler, criar, compactar (zip/unzip), checar tipo MIME e mudar encoding de arquivos.
- Date Helper — formatar datas, somar/subtrair tempo, calcular diferença entre datas, capturar o timestamp atual.
- Text Helper — replace, split, trim, substring, convert case e extração com regex.
- Math — operações aritméticas, arredondamento (round/floor/ceil), máx/mín/absoluto e número aleatório.
- Data Mapper — achatar (flatten) e reorganizar payloads JSON aninhados para facilitar o mapeamento visual.
- Data Summarizer — somar, calcular média, mín, máx ou contagem de uma lista inteira de uma só vez, sem abrir um laço.
- Crypto — gerar HMAC, hash, e criptografar/descriptografar dados sensíveis.
- JSON / XML / HTML — parse, stringify e validação de JSON; conversão XML↔JSON (útil para NF-e); conversão HTML↔Markdown.
- FTP / SFTP — upload e download de arquivos em servidores corporativos.
Tratamento de erros: não deixe o flow falhar às cegas
Nenhuma integração séria deve falhar em silêncio ou de forma imprevisível. Cada step oferece, na seção Error handling, dois controles que mudam o comportamento do flow diante de uma falha.
Add Error Handler cria duas ramificações no step: uma de Success e uma de Failure. Quando o step falha, o fluxo desvia para o caminho de Failure em vez de simplesmente interromper a execução. Isso permite tratar o erro de forma deliberada — registrar o ocorrido, abrir um card de exceção, notificar um responsável — em vez de deixar o run morrer sem destino.
Tentar novamente ao falhar (retry) faz o step tentar até 4 vezes antes de marcá-lo como falho. É o tratamento certo para instabilidades passageiras — um erro transitório de rede ou um 5xx/429 momentâneo de uma API externa costuma se resolver sozinho na segunda ou terceira tentativa. Vale lembrar que retry não corrige erro de requisição (um 4xx continuará falhando a cada tentativa): para esses, o caminho é o handler de Failure, não a repetição.
Fluxos idempotentes: a contrapartida obrigatória do retry
Há uma consequência direta de habilitar retry, e de qualquer reexecução manual de um run com falha: o step pode rodar mais de uma vez com a mesma entrada. Se esse step cria um registro, repetir a execução pode criar duplicatas. Um card de fatura criado em duplicidade vira risco de pagamento dobrado; um registro repetido contamina relatórios.
A defesa é desenhar o flow para ser idempotente: executá-lo uma ou várias vezes com a mesma entrada produz sempre o mesmo resultado, sem efeitos colaterais adicionais. O padrão é simples e usa uma chave única vinda da origem (número da NF, ID do pedido, ID da transação):
- Antes de criar, busque no Pipefy se já existe um registro com aquela chave (search-before-create).
- Use um Router: se não existe, cria; se já existe, não faz nada (ou atualiza, num padrão de upsert).
- Grave a chave única em um campo de controle, para que a próxima reexecução a encontre.
Assim, retry e reexecução deixam de ser uma ameaça e passam a ser uma rede de segurança: o flow se recupera de falhas transitórias sem nunca duplicar dados.
Caso de uso: integração de aprovação de contratos
Um processo de aprovação de contratos no Pipefy precisa, quando um card avança para a fase "Aprovado", criar um registro no sistema jurídico externo, notificar o solicitante por e-mail e atualizar um campo de status no card original.
A estrutura do flow: trigger por evento (card moved para a fase "Aprovado"), um step de criação de registro no sistema jurídico via peça HTTP, um Router que verifica se a criação foi bem-sucedida (código 200) ou falhou, e dois caminhos: no caminho de sucesso, um step de envio de e-mail e um step de atualização do card; no caminho de falha, um step de notificação para o time de operações investigar.
Esse flow tem cinco steps além do trigger. Construí-lo e testar tudo só no final significa que qualquer problema no segundo step só aparece depois de cinco configurações feitas. O ciclo correto é testar cada step antes de adicionar o próximo.
O ciclo de testes que evita retrabalho
O Integrações Pipefy não permite usar os dados de saída de um step nos steps seguintes enquanto aquele step não tiver sido testado. Isso não é limitação: é uma proteção. Um step não testado não tem estrutura de dados conhecida, e mapear campos de uma estrutura desconhecida gera mapeamentos que quebram na primeira execução real.
O ciclo correto é iterativo: configure o trigger, teste-o, revise os dados de saída no painel lateral. Adicione o primeiro step de ação, configure-o usando os dados do trigger, teste-o. Revise os dados de saída. Só então adicione o segundo step. Repita até o último step. Execute o Test Flow para verificar o flow completo em sequência. Só depois publique.
Test Action executa a ação no sistema real: cria um card de verdade, envia um e-mail de verdade, cria um registro de verdade. Use dados de teste com nomes e valores claramente identificáveis como teste para evitar poluir o ambiente de produção com dados gerados durante o desenvolvimento.
Runs: o histórico que permite diagnóstico
Toda execução do flow gera uma execução. A aba execuções mostra o histórico completo: execuções bem-sucedidas, falhas e execuções parcialmente concluídas. Cada execução listada detalha os dados que passaram entre os steps e o erro exato que causou a falha, quando houver. Esse histórico é o ponto de partida para qualquer diagnóstico em produção.
Retry: duas opções com propósitos distintos
Quando uma execução falha, duas opções de retry estão disponíveis. Retry from Failed Step retoma a execução a partir do step exato onde ocorreu a falha, usando os mesmos dados da execução original e a mesma versão do flow. É a opção correta para falhas transitórias: timeout de API, instabilidade de rede, indisponibilidade momentânea de um sistema externo. O flow já estava correto; o problema foi externo e temporário.
Retry on Latest Version cria uma nova execução completa e executa o flow do início, usando a versão publicada atual. É a opção correta após corrigir um bug ou atualizar a lógica do flow. A execução original falhou por um problema no flow; a versão nova resolve; o retry reprocessa com a lógica corrigida.
Usar Retry on Latest Version num run que falhou por erro transitório, quando nenhuma alteração foi feita no flow, cria um run duplicado que pode gerar dados inconsistentes no sistema destino: dois registros criados, dois e-mails enviados, dois updates aplicados. Escolha o tipo de retry com base na causa da falha, não na urgência de resolver.
Checklist de conclusão
☐ Os elementos de um flow e o papel de cada um
☐ Por que o Pipefy bloqueia uso de dados de um step não testado
☐ A diferença entre Retry from Failed Step e Retry on Latest Version
