🔐 Disponível para clientes com o add-on de Custom Integrations
👤 Para quem está construindo ou revisando flows de integração
🎯 Nível: iniciante-intermediário
A maioria dos erros em flows de integração não acontece na configuração do trigger nem na escolha das ações. Acontece no meio: na hora de passar um dado de um passo para o próximo. O campo certo não aparece no seletor, a estrutura do dado é diferente do esperado, um campo opcional que estava vazio derruba o flow inteiro.
O Data selector, que é o mapeamento de dados, no Integrações Pipefy funciona a partir de um Visual Mapper: você clica no campo que quer preencher e um seletor abre com todos os dados disponíveis dos passos anteriores, organizados em árvore. O conceito é simples, mas os dados que chegam de APIs reais têm estruturas que exigem conhecimento específico para navegar corretamente. Entender os quatro padrões deste artigo elimina a maior parte das dificuldades que aparecem na construção de flows.
📖 O que você vai entender aqui:
Como o Data Selector funciona
Cada passo do flow gera um conjunto de dados de saída. O Data Selector torna esses dados disponíveis para os passos seguintes sem que você precise saber de antemão a estrutura exata do payload. Clique em qualquer campo de um passo, o seletor abre à lateral e exibe os dados de todos os passos anteriores organizados por origem.
Para que os dados apareçam no seletor, o passo que os gera precisa ter sido testado antes. O teste executa o passo com dados reais ou dados de amostra e registra a estrutura da resposta. Sem esse teste, o seletor não sabe o que aquele passo retorna e os campos ficam invisíveis. Testar cada passo durante a construção do flow é parte do processo de desenvolvimento, não um extra opcional.
Use a opção Generate Sample Data quando o sistema externo não estiver disponível para um teste real. Os dados gerados são suficientes para mapear a estrutura e avançar na construção do flow. Antes de publicar, substitua por um teste com dados reais para confirmar que a estrutura corresponde ao que o sistema efetivamente retorna.
Os quatro padrões de Data Mapping
1. Objetos simples
A maioria dos campos de uma API retorna como pares de chave e valor diretos: nome, e-mail, status, ID. São os mais fáceis de mapear: expanda o passo de origem no seletor, clique no campo desejado e insira. O campo de destino recebe o valor.
Um exemplo concreto: um flow de onboarding recebe dados de um card do Pipefy via trigger. O passo seguinte precisa criar um registro no HRIS com o nome do colaborador e a data de início. No seletor, expanda os dados do trigger, localize os campos correspondentes e mapeie um a um para os campos do passo de criação no HRIS.
2. Objetos aninhados
APIs raramente retornam dados completamente aninhados. É comum que uma resposta tenha objetos dentro de objetos: um campo "address" que contém "street", "city" e "zipcode", ou um campo "card" que contém "id", "title" e "fields". No Visual Mapper, esses objetos têm uma seta que permite expandi-los. Clique na seta para abrir o nível seguinte e continue navegando até o campo específico que precisa.
O caminho percorrido fica visível no seletor: data > card > id, por exemplo. Esse caminho é o que o Pipefy usa para extrair o valor correto em cada execução. Se a estrutura da API mudar e o campo mudar de posição na hierarquia, o mapeamento precisa ser atualizado.
3. Arrays
Quando um dado é uma lista, o seletor exibe os itens numerados entre colchetes: [1], [2], [3]. Cada número representa uma posição na lista. Para acessar o conteúdo de um item específico, expanda o índice correspondente e navegue pelos campos internos.
O ponto de atenção aqui é a indexação. Arrays em APIs geralmente começam no índice zero ou no índice um, dependendo da implementação. Mapear o índice errado retorna um dado incorreto ou vazio sem gerar um erro explícito. Sempre confirme com dados reais qual índice corresponde ao item que o flow precisa antes de publicar.
Mapear um índice fixo num array que muda de tamanho entre execuções é uma fonte frequente de bugs silenciosos. Se o array pode ter quantidades variáveis de itens, use um Loop para iterar sobre todos os elementos em vez de referenciar uma posição fixa.
4. JSON Path para estruturas profundas
Algumas APIs retornam estruturas muito profundas ou complexas demais para navegar eficientemente pelo seletor visual. Nesses casos, JSON Path permite acessar qualquer campo diretamente com uma expressão de texto, sem precisar expandir cada nível manualmente.
A sintaxe é direta: data.card.fields[0].value acessa o campo "value" do primeiro item do array "fields" dentro do objeto "card" dentro de "data". JSON Path é especialmente útil dentro da peça Code, onde o dado está disponível como variável e a expressão funciona nativamente. Para mapeamentos visuais, o seletor cobre a maioria dos cenários com mais legibilidade.
Tratamento de dados ausentes: o passo que ninguém faz até precisar
Campos opcionais existem em qualquer processo. Um card pode ser criado sem responsável atribuído. Um formulário pode ter campos que só aparecem com lógica condicional. Uma API pode retornar a um campo vazio dependendo do estado do registro.
Quando um flow tenta usar um dado que não existe, o comportamento padrão é falhar. Sem tratamento explícito, o flow para na primeira execução em que o campo opcional está vazio, mesmo que todas as outras execuções funcionem perfeitamente. A forma correta de lidar com isso é usar um Router antes do passo que depende do dado, com uma condição que verifica se o campo existe. Se existir, o flow segue o caminho que usa o dado. Se não existir, segue um caminho alternativo ou encerra a execução de forma controlada.
Flows testados apenas com casos felizes chegam à produção com bugs que só aparecem quando os dados são incompletos. Durante o desenvolvimento, teste pelo menos um cenário em que cada campo opcional esteja ausente. Esse teste revela os pontos de falha antes que o ambiente produtivo os encontre.
Checklist de conclusão
☐ Por que testar cada passo durante a construção é obrigatório para o seletor de dados funcionar
☐ A diferença entre navegar objetos aninhados, arrays e usar JSON Path
☐ Por que indexação fixa em arrays é arriscada em flows de produção
☐ Como um Router protege o flow de falhas causadas por dados ausentes
