Rastreamento de cliques no Pipedrive: deals gerados a partir de cliques em short links

O rastreamento de cliques do Pipedrive no Elido transforma os marcos dos short links em eventos de pipeline. Quando um dos seus links ultrapassa 100, 1.000 ou 10.000 cliques, um cron de 5 minutos cria um deal no pipeline e no estágio do Pipedrive que você selecionou, com o slug do link, a fonte UTM e um link direto ao Elido nas notas do deal. Sem Zapier no meio, sem exportação manual, sem lembrete no calendário para verificar relatórios de links.

Esse é o título. A mecânica importa mais, por isso este artigo percorre as três coisas que as equipes de sales ops precisam entender antes de ativar esse recurso. Primeiro, como o fluxo de Connect realmente funciona: onde fica o token de API pessoal, o que o seletor de pipeline lê e como o token é armazenado depois que você o cola. Segundo, o que o cron de limites faz em cada execução e como ele evita criar deals duplicados quando um link se torna viral da noite para o dia. Terceiro, como estender a integração além dos três limites padrão, para contagens de cliques personalizadas, triggers com escopo de UTM e campos personalizados do Pipedrive, usando o Elido SDK e um pequeno handler de webhook.

O Pipedrive passou para Live no Elido em 22 de maio de 2026. Antes disso, ficou duas semanas em Beta enquanto resolvíamos casos extremos em torno dos IDs de estágio e da rotação de tokens. O código da integração fica em services/api-core/internal/integrations/pipedrive/ caso você hospede localmente e queira ler o código-fonte. Tudo neste artigo corresponde ao que está em produção, não a um roadmap.

Conectar o Pipedrive em dois minutos

Abra o catálogo de integrações no seu workspace do Elido e clique no card do Pipedrive. O modal de conexão pede primeiro uma coisa: um token de API pessoal. Você o obtém na sua conta do Pipedrive abrindo o menu de perfil, escolhendo Preferências pessoais e depois a aba API. O próprio guia do Pipedrive sobre how to find the Personal API token tem o caminho exato com capturas de tela, já que a interface deles muda a cada trimestre mais ou menos.

Cole o token. O Elido faz duas coisas em segundo plano. Valida o token chamando GET /users/me contra a API do Pipedrive, o que confirma que o token está ativo e nos diz a qual empresa do Pipedrive ele pertence. Também busca a lista de pipelines e estágios daquela empresa, para que o próximo passo no modal mostre opções reais, não campos de texto livre.

O modal então faz mais duas perguntas. Em qual pipeline os novos deals devem ser criados? Em qual estágio desse pipeline? Os menus suspensos são preenchidos com seus dados ao vivo do Pipedrive. Se você tem três pipelines chamadas Inbound, Outbound e Partners, você vê essas três. Escolha a que se encaixa no trabalho - geralmente Inbound para sinais de marketing - e depois o primeiro estágio de qualificação. Clique em Conectar.

O que acontece com o token após a conexão. O Elido o criptografa antes que ele toque o Postgres, usando criptografia de envelope com uma chave de criptografia de dados por tenant encapsulada por uma chave KMS do workspace. O blob criptografado é o que fica na tabela integration_credentials. O token em texto simples existe apenas na memória pelo tempo de uma única chamada de API, e nunca o registramos em logs, nem mesmo com verbosidade de debug. Se você rotacionar o token no Pipedrive, a próxima execução do cron recebe um 401 e o Elido marca a integração como precisando de reautenticação, o que aparece como um banner no workspace, não como uma falha silenciosa. A higiene de rotação é sua responsabilidade; a falha é barulhenta.

O seletor de pipeline é um detalhe pequeno mas importante. Um modo de falha comum em integrações de CRM é criar deals no pipeline errado porque a integração foi construída quando a empresa tinha um pipeline e agora tem seis. Deixar o usuário escolher na conexão, e mostrar a lista atual em vez de um cache de um mês atrás, elimina toda essa classe de erros. Você também pode reconectar a qualquer momento para mudar o destino do seletor sem perder o histórico de limites.

O que o cron de 5 minutos realmente faz

Dentro de services/api-core há um job chamado click_threshold_hook. Ele é executado a cada cinco minutos. Em cada tick, faz três coisas em ordem, por workspace que tenha o Pipedrive conectado.

Primeiro, pergunta ao ClickHouse pelos totais de cliques por link atualizados nos últimos seis minutos, mais um buffer de um minuto para cobrir eventos tardios. O ClickHouse armazena os eventos de clique em uma tabela clicks particionada por data, e o rollup consultado é uma view materializada com chave pelo ID do short link. A consulta retorna links cujos totais mudaram desde a última execução do cron, não a tabela inteira. Em um workspace com 50.000 links ativos e um padrão de cliques normal, essa consulta fica abaixo de 200 ms.

Segundo, compara o novo total de cada link com os limites registrados. Os limites padrão são 100, 1.000 e 10.000. Para cada link, o Elido rastreia o maior limite já atingido em uma pequena linha link_threshold_state com chave pelo ID do link. Se um link estava em 80 cliques na última execução e agora está em 240, a comparação mostra que o limite de 100 foi cruzado e o de 1.000 ainda não foi atingido. Marcamos 100 como atingido e colocamos uma criação de deal na fila. Se um link pulou de 80 para 1.200, tanto 100 quanto 1.000 foram cruzados, então colocamos duas criações na fila.

Terceiro, para cada deal na fila, o Elido chama a API de Deals do Pipedrive com um POST para /deals. O corpo define o ID do pipeline e o ID do estágio do seletor de conexão, nomeia o deal de forma legível como Link <slug> atingiu <limite> cliques, e escreve a fonte UTM, o meio e a campanha na nota do deal junto com um link clicável de volta para a view de analytics do Elido para aquele link. Também salvamos o ID do link em um campo personalizado do Pipedrive se o workspace tiver um configurado, o que torna possível consultar o Pipedrive mais tarde por todos os deals vinculados a um link específico do Elido.

Algumas coisas que este cron não faz. Ele não retenta indefinidamente erros 5xx do Pipedrive. Se o Pipedrive retornar 500 ou 503, tentamos novamente duas vezes com backoff exponencial dentro do mesmo tick do cron e então deixamos o trabalho para o próximo tick. O limite de taxa do Pipedrive é de 100 requisições por 2 segundos por token de empresa na prática, o que é espaço de sobra para os volumes que a maioria das equipes atingirá. Também não criamos deals para links marcados como teste, internos ou de propriedade de um membro do workspace que optou por não participar da sincronização CRM nas suas configurações pessoais.

A prevenção de duplicatas foi a parte que mais iterações exigiu. A primeira versão tinha uma race condition: se dois pods do cron rodassem em sobreposição, ambos podiam ver o mesmo link cruzar 100 e ambos podiam fazer POST de um deal. Resolvemos isso com um advisory lock do Postgres no ID do workspace no início de cada tick do cron, mais uma restrição única em (link_id, threshold) em link_threshold_state. Se o segundo pod tentar inserir uma linha duplicada, o Postgres a rejeita e o POST na fila é descartado antes de chegar ao Pipedrive. Cinto e suspensórios.

Ir além dos três limites padrão

Os limites incluídos são 100, 1.000 e 10.000. A maioria das equipes os mantém porque se encaixam naturalmente em uma narrativa de vendas. Cem cliques são um sinal fraco que vale uma olhada. Mil é uma campanha que vale uma ligação. Dez mil é quente o suficiente para que um vendedor já esteja se movendo. Dito isso, você pode querer números diferentes, e o SDK suporta isso.

A integração Pipedrive do Elido aceita uma lista de limites personalizada no nível do workspace. Você a define pelo endpoint PATCH /v1/workspaces/:id/integrations/pipedrive com um corpo JSON como {"thresholds": [50, 500, 5000, 50000]}. O cron pega a nova lista no próximo tick. A tabela de estado preserva o histórico, então alterar os limites não cria deals retroativamente, apenas muda quais cruzamentos futuros disparam um evento.

Para triggers mais ricos, o SDK expõe um hook CreateDeal que você pode registrar de qualquer serviço. O caso clássico: criar um deal apenas quando um link cruza um limite E a fonte UTM é sua campanha de social paga, não o seu blog orgânico. Isso é um filtro de uma linha dentro do hook. Outro caso comum: disparar apenas em links dentro de uma pasta específica do Elido, porque essa pasta é sua pasta de campanha e todo o resto é ruído. O mesmo hook também pode definir campos personalizados do Pipedrive como Fonte do Deal, Canal de Lead, ou qualquer taxonomia que sua equipe de sales ops use. O guia de encaminhamento de conversões cobre o mesmo padrão de hook para plataformas de anúncios; o caso do Pipedrive é estruturalmente idêntico.

Uma nota sobre campos personalizados. O SDK aceita tanto o rótulo legível por humanos quanto a chave de API com hash que o Pipedrive usa internamente. Se você referenciar um rótulo que não existe na empresa conectada, o deal ainda é criado e o campo ausente é registrado como aviso, nunca como erro. Um campo personalizado ausente não deve bloquear um sinal de venda real.

Equipes com muitos links por campanha às vezes querem agregar limites em uma pasta. Defina aggregation: "folder" na configuração de integração do workspace e o cron agrupa os totais de cliques por pasta e então verifica a soma. O deal nomeia a pasta e lista os três links que mais contribuíram nas notas.

Onde fica o token e como rotacioná-lo

Uma seção curta porque aparece em todas as revisões de segurança. O token de API pessoal é criptografado em repouso usando AES-256-GCM com uma chave de criptografia de dados por tenant. O DEK é ele mesmo encapsulado por uma chave de nível de workspace no nosso KMS, e apenas o processo api-core pode desencapsulá-lo. Não há token em texto simples em nenhum log, backup ou rastro de erro. Testamos isso com uma injeção de falha que forçou um 401 do Pipedrive no meio de uma requisição, e o caminho de erro limpa o token da resposta antes que ela chegue ao Sentry.

Para rotacionar: gere um novo token de API pessoal no Pipedrive, revogue o antigo, depois cole o novo no modal de conexão do Elido. A integração valida o novo token, o substitui no lugar e o próximo tick do cron o usa. Se você esquecer de atualizar o Elido após revogar o token antigo, o próximo tick do cron recebe um 401 e a integração entra no estado Necessita de Reautenticação, visível como um banner amarelo no painel do workspace. Sem tokens mortos silenciosos.

No self-host o KMS é configurável: com suporte em arquivo por padrão, troque por HashiCorp Vault ou o KMS da sua nuvem. O ADR-0036 cobre a forma longa.

Como isso se encaixa em um funil mais amplo

Os triggers de deals do Pipedrive a partir de cliques são uma peça de um padrão maior. Contagens de cliques são um indicador antecedente, não um número de receita, então você geralmente quer que eles fluam para um CRM onde vive o resto do contexto de vendas. O deal é a entrega: o marketing fez seu trabalho, as vendas o pegam. A partir daí, seus fluxos normais do Pipedrive assumem: atribuir o deal a um vendedor, pontuá-lo, movê-lo pelos estágios, fechá-lo.

Se você também está encaminhando conversões para plataformas de anúncios, os mesmos dados de cliques alimentam ambos os fluxos. O recurso de rastreamento de conversões cuida do lado dos anúncios, a integração do Pipedrive cuida do lado do CRM, e os dois nunca disputam o mesmo evento. Vemos essa combinação com mais frequência na página de solução para profissionais de marketing, onde toda a stack vai da aquisição paga por links com marca até um funil de CRM.

Para analistas que querem manter seus números honestos, dois artigos anteriores cobrem as preocupações no topo do funil. Short link analytics: what to measure cobre quais métricas de cliques realmente se correlacionam com receita, e Track UTM end to end cobre a higiene de UTM que torna as notas de deal úteis em vez de ruidosas. Os dois combinam bem com essa integração, já que o deal que o Pipedrive cria é tão útil quanto os dados UTM que ele carrega.

Um último detalhe sobre planos. A integração do Pipedrive está em todos os níveis pagos do Elido, e o teste de 14 dias a inclui para que você possa validar sua lista de limites antes de assinar. Workspaces gratuitos podem criar a conexão para teste, mas o cron não dispara para links gratuitos. A página de preços tem o detalhamento por nível.

Lista de verificação de configuração

Imprima, faça uma vez.

1. No Pipedrive: menu de perfil, Preferências pessoais, aba API, copie o token.
2. No Elido: Integrações, card do Pipedrive, Conectar.
3. Cole o token. Aguarde a validação.
4. Escolha o pipeline e o estágio. Padrão: Inbound e o primeiro estágio de qualificação.
5. Clique em Conectar.
6. Opcional: edite a lista de limites se 100/1k/10k não corresponder ao seu processo de vendas.
7. Opcional: registre um hook CreateDeal personalizado para filtros UTM ou agregações de pastas.
8. Aguarde cinco minutos. Envie alguns cliques de teste. Observe o primeiro deal chegar.

É isso. Se você faz self-host, também quer verificar se o cron está habilitado conferindo que kubectl get cronjob api-core-click-threshold-hook retorna um agendamento ativo. No Elido Cloud o cron é gerenciado para você.