🔐 Disponível para clientes com o add-on de Custom Integrations
👤 Para quem precisa conectar sistemas sem conector nativo disponível
🎯 Nível: intermediário
O Pipefy Integrations Hub oferece conectores prontos para os principais sistemas do mercado. Mas a realidade de qualquer operação inclui sistemas internos, plataformas regionais, APIs proprietárias e ferramentas que nenhum catálogo de conectores vai cobrir completamente. Para esses casos, existe a opção HTTP e HTTP (OAuth2).
A peça HTTP permite que qualquer flow se comunique com qualquer endpoint externo que aceite requisições HTTP. Sem precisar de um conector dedicado, sem depender do roadmap de integrações. Se a API existe e é acessível, o flow consegue falar com ela.
📖 O que você vai entender aqui:
Conector dedicado ou peça HTTP: como decidir
A regra geral é simples: use um conector dedicado sempre que existir um disponível para o sistema que você quer integrar. Conectores dedicados já tratam autenticação, mapeamento de dados e casos de borda específicos da plataforma. São mais fáceis de configurar e de manter.
A peça HTTP entra quando não há conector disponível, ou quando você precisa de controle granular sobre a requisição que um conector padrão não oferece. Na ferramenta, chamadas HTTP se dividem em duas abordagens fundamentais de acordo com o modelo de segurança do sistema de destino:
- HTTP (Padrão): É a escolha ideal para APIs que utilizam autenticação estática e simplificada, como chaves de API (API Keys), tokens Bearer fixos ou autenticação básica (Basic Auth por usuário e senha). É a opção mais rápida de configurar, pois basta colar a chave referenciada de Variables diretamente nos parâmetros ou headers.
- HTTP OAuth2: Criada especificamente para plataformas modernas que exigem o fluxo dinâmico e seguro do protocolo OAuth 2.0 (com telas de consentimento). A grande vantagem técnica desta opção é que o produto gerencia todo o ciclo de vida das credenciais para você: ele armazena o Access e o Refresh Token e realiza a renovação automática das chaves em segundo plano, impedindo que o seu fluxo quebre por token expirado.
A peça HTTP exige que você conheça a documentação da API que vai consumir: quais métodos ela aceita, como espera receber os dados, quais headers são obrigatórios e qual é o modelo de autenticação exigido. Esse conhecimento não está no Pipefy. Ele vem da documentação do sistema externo.
As decisões que definem o comportamento da integração
Configurar a peça HTTP envolve escolhas técnicas que impactam diretamente a confiabilidade do flow. Algumas merecem atenção antes de entrar em produção.
Método e estrutura da requisição
O método HTTP define o que você quer fazer na API: GET para consultar dados, POST para criar registros, PUT ou PATCH para atualizar, DELETE para remover. Cada API define quais métodos aceita em cada endpoint. Use a documentação da API como referência, não suposições.
Headers (Cabeçalhos) são o local correto para passar credenciais de autenticação, como tokens Bearer ou chaves de API. Query params (Consultar parâmetros) vão para parâmetros de filtro e paginação que a API espera na URL. O body (Corpo) carrega o payload quando o método exige o envio de dados, normalmente estruturado em JSON ou form data.
Para garantir a segurança e a flexibilidade da integração, evite fixar chaves secretas ou dados confidenciais diretamente nesses campos. Em vez disso, utilize a aba Variables (Variáveis) do Seletor de Dados para injetar essas informações dinamicamente. Ao referenciar uma variável usando a estrutura nativa da plataforma, você mantém o fluxo reutilizável, facilita a manutenção entre ambientes e protege dados críticos contra exposição direta no texto estruturado da requisição.
Nunca coloque credenciais diretamente na URL ou no body da requisição. Além do risco de exposição em logs, muitas APIs rejeitam autenticação fora dos headers. Use sempre o campo de headers para Authorization e chaves de acesso.
Comportamento em caso de falha
APIs falham. Servidores ficam indisponíveis, timeouts acontecem e respostas chegam fora do formato esperado. Para gerenciar essas instabilidades, a peça HTTP disponibiliza o campo Em caso de falha, permitindo determinar com precisão cirúrgica como o seu fluxo deve reagir a cada tipo de resposta técnica.
Ao expandir o menu de seleção, você encontrará opções divididas entre políticas de repetição e políticas de continuidade do fluxo:
🔄 Estratégias de Repetição (Retries)
- Repetir todos os erros (4xx, 5xx): Força o sistema a tentar executar a chamada novamente, independentemente de a falha ter sido causada por um erro na requisição (cliente) ou no servidor externo.
- Tentar novamente em erros internos (5xx): É a escolha ideal para mitigar instabilidades temporárias de rede ou indisponibilidades momentâneas do servidor parceiro.
- Não tente novamente: O fluxo descarta qualquer tentativa de reprocessamento imediato assim que a primeira falha é detectada.
🛤️ Estratégias de Continuidade
- Continuar fluxo em todos os erros: Permite que o flow avance para os próximos passos mesmo que a chamada HTTP falhe totalmente. Faz sentido quando a ação é puramente acessória e o processo principal não pode parar.
- Continuar fluxo em erros de 4xx: Permite a continuidade se o erro for do lado do cliente (como um mapeamento incorreto temporário), mas interrompe a execução caso o servidor de destino caia (erros 5xx).
- Não continue (pare o fluxo): É a opção padrão e mais segura do sistema. Se a API falhar, o fluxo é interrompido imediatamente para proteger a integridade dos dados.
Risco de falha silenciosa: as opções de Continuar fluxo são ferramentas poderosas, mas trazem riscos severos de inconsistência. Use-as estritamente quando a resposta da API não for crítica para as decisões ou registros dos passos seguintes. Forçar a continuidade em chamadas essenciais mascara falhas reais e gera dados corrompidos que são extremamente difíceis de rastrear nos logs depois.
Usando a resposta da API no flow
Depois que a peça HTTP executa, a resposta fica disponível para os passos seguintes via Data Selector. Você pode acessar o corpo da resposta para extrair valores específicos, usar o código de status para ramificar o flow com um Router (200 para sucesso, 404 para não encontrado, 500 para erro de servidor) e recuperar headers da resposta quando necessário.
Para que esses dados fiquem disponíveis no Data Selector, é preciso testar a peça durante a construção do flow. O teste gera os dados de exemplo que o Pipefy usa para mapear os campos disponíveis. Sem o teste, o Data Selector não sabe o que a API retorna e os campos não aparecem para seleção.
Um caso concreto: consulta um sistema legado de estoque
Um processo de aprovação de compras no Pipefy precisa validar a disponibilidade de estoque antes de avançar. O sistema de estoque é um ERP legado da empresa, sem conector nativo disponível no Pipefy Integrations Hub, mas com uma API REST documentada.
A peça HTTP faz uma requisição GET para o endpoint de consulta de estoque, passando o código do item como query param e o token de autenticação interno no header Authorization. A resposta retorna a quantidade disponível em JSON. Um Router no flow seguinte lê esse valor: se acima do mínimo, avança para aprovação; se abaixo, move o card para uma fase de revisão e notifica o solicitante.
Sem a peça HTTP, esse dado precisaria ser consultado e inserido manualmente por alguém do time de compras. Com ela, o flow decide sozinho e o time atua apenas nos casos que realmente precisam de intervenção humana.
Antes de colocar em produção
- Confirme que a API usa HTTPS. Requisições em HTTP simples expõem dados em trânsito.
- Verifique os termos de uso da API, especialmente limites de chamadas por minuto ou por dia. Um flow de alto volume pode atingir rate limits rapidamente.
- Documente no próprio flow qual API está sendo chamada e para que finalidade. Flows sem contexto viram dívida técnica.
Checklist de conclusão
☐ Quando usar a peça HTTP em vez de um conector dedicado
☐ Qual a diferença de comportamento entre Retry, Continue on Failure e No Error on Failure
☐ Por que testar a peça é obrigatório para usar os dados da resposta no Data Selector
☐ Onde colocar credenciais de autenticação em uma requisição HTTP
