🔐 Disponível para clientes com o add-on de Custom Integrations
👤 Para quem constrói flows que interagem com pipes e databases do Pipefy
🎯 Nível: iniciante-intermediário
O conector Pipefy é a peça que conecta o Integrações Pipefy ao próprio Pipefy. É por onde flows externos leem e escrevem dados em pipes e databases, e por onde eventos internos do Pipefy disparam flows para sistemas externos. Entender quando usar cada trigger e como escolher a ação correta para cada situação reduz o número de steps num flow, melhora a rastreabilidade e evita buscas desnecessárias que consomem tasks sem retorno real.
📖 O que você vai entender aqui:
Pipe ou Database: a primeira decisão
O conector Pipefy tem dois grupos de triggers e dois grupos de ações: um para cards em pipes e outro para registros em databases. A distinção parece óbvia, mas tem implicações de design que aparecem quando um processo usa as duas estruturas.
Pipes são processos: têm fases, responsáveis, histórico de movimentação e um ciclo de vida definido. Databases são tabelas de referência: catálogos de produtos, bases de fornecedores, listas de usuários. Quando o evento que dispara o flow acontece dentro de um processo, o trigger correto é de card. Quando acontece numa tabela de dados, o trigger correto é de record. Misturar os dois grupos por imprecisão cria flows que monitoram a estrutura errada e deixam de disparar nos momentos relevantes.
Um sinal de que o design pode estar errado: se você precisa de um trigger de card para depois buscar dados no database, ou vice-versa, a estrutura no Pipefy provavelmente está correta e o flow está seguindo o caminho natural. Se o trigger e o dado relevante vivem em estruturas diferentes sem essa necessidade clara, vale revisar onde o processo e os dados de referência estão armazenados.
Card Triggers: qual usar para cada momento do processo
O Pipefy conector oferece nove triggers de card, cada um mapeado para um momento específico no ciclo de vida de um card. A maioria dos flows de integração usa três com alta frequência.
Card created é o trigger para automações que precisam acontecer no exato momento em que um processo começa. Onboarding de clientes, abertura de chamado, entrada de pedido: qualquer evento de início de processo. Card moved é o trigger mais usado em fluxos de acompanhamento. Ele dispara quando um card muda de fase, o que representa uma transição de estado no processo. É o trigger correto para notificações de status, sincronizações com sistemas externos e criação de tarefas derivadas.
Card field updated é o trigger para sincronização de dados. Quando um campo específico muda de valor, o flow pode propagar essa mudança para sistemas externos sem depender de uma mudança de fase. É útil quando o processo não avança de fase mas um dado relevante foi atualizado, como a atribuição de um responsável ou a atualização de um valor de contrato.
Os triggers de tempo, como Card overdue, Card late e Card expired, são menos usados mas têm valor estratégico em processos com SLA. Um card que ultrapassa o prazo sem resolução pode acionar automaticamente uma escalada ou uma notificação para o gestor responsável, sem depender de monitoramento manual.
Como buscar um card: quatro métodos, critérios distintos
Um padrão frequente em flows de integração é precisar dos dados completos de um card para executar uma ação em outro sistema. O trigger fornece alguns campos, mas não necessariamente todos. Para recuperar os dados completos, o flow precisa de uma ação de busca. O conector Pipefy oferece quatro métodos, e a escolha entre eles tem implicações de confiabilidade e desempenho.
Get card by ID
É o método mais direto, buscando todos os campos. Cada card no Pipefy tem um ID único e imutável. Se o flow tem acesso ao ID, seja do trigger ou de um passo anterior, essa é sempre a forma preferencial de busca. Uma chamada, uma resposta determinística, sem ambiguidade.
Get cards by field value
Busca cards que têm um campo específico com um valor específico. É útil quando o identificador de negócio disponível no sistema externo, como um CNPJ ou um número de pedido, está armazenado num campo do card. O risco é que múltiplos cards podem ter o mesmo valor num campo: o flow precisa tratar o cenário em que a busca retorna mais de um resultado.
Get cards by phase
Retorna todos os cards atualmente em uma fase específica. Útil para flows de processamento em lote que precisam operar sobre todos os cards numa fase ao mesmo tempo, como um relatório diário ou uma sincronização de status. Não é adequado para buscar um card específico porque o resultado é uma lista inteira, não um item único.
Get cards by title
Busca cards pelo texto do título. É o método menos confiável para uso programático porque títulos mudam, podem ser duplicados e raramente são usados como identificadores únicos em integrações. Adequado para buscas ad hoc ou flows de baixa criticidade onde nenhum identificador mais preciso está disponível.
A hierarquia de confiabilidade para busca de card é: ID (preferencial) > campo de identificador único (CNPJ, número de pedido) > fase (para processamento em lote) > título (evitar em produção). Quanto mais abaixo na hierarquia, mais o flow precisa de lógica de tratamento de ambiguidade.
Caso de uso: sincronização de CRM com onboarding
Um flow de onboarding é disparado por um trigger do CRM: quando uma oportunidade é marcada como "Ganha", um evento chega ao Pipefy Integrations Hub via webhook. O flow precisa criar um card no pipe de onboarding com os dados do cliente e, em seguida, buscar os dados completos do card recém-criado para registrar o ID gerado pelo Pipefy no CRM.
A sequência de ações usa três operações do conector Pipefy: Create card para criar o card no pipe de onboarding com os dados mapeados do payload do CRM, Get card by ID para recuperar os detalhes completos do card recém-criado incluindo o ID gerado, e Update record para gravar esse ID numa tabela de database que serve de mapeamento entre os IDs do CRM e os IDs do Pipefy. Esse mapeamento é o que permite que execuções futuras encontrem o card correto a partir do identificador do CRM.
Custom API Call: quando as ações padrão não chegam
O conector Pipefy cobre as operações mais comuns com ações pré-construídas. Para operações que não estão no catálogo, como consultas GraphQL específicas, mutações customizadas, o Custom API Call permite fazer qualquer chamada à API GraphQL do Pipefy diretamente.
Assim como o conector de Code, o Custom API Call entrega flexibilidade total ao custo de maior responsabilidade técnica: quem usa precisa conhecer a API do Pipefy, construir a query ou mutation corretamente e tratar os erros que podem ocorrer. Para operações críticas e de alto volume, uma ação padrão é sempre mais segura que uma chamada customizada, porque abstrai os detalhes da API e é mantida pelo time do Pipefy.
Checklist de conclusão
☐ Quando usar triggers de card versus triggers de record
☐ Qual método de busca de card usar para cada contexto
☐ Quando Custom API Call é preferível às ações padrão e quando não é
