Tracciamento clic Pipedrive: deal generati dai clic sui short link

Il tracciamento dei clic Pipedrive in Elido trasforma i traguardi dei short link in eventi di pipeline. Quando uno dei tuoi link supera 100, 1.000 o 10.000 clic, un cron di 5 minuti crea un deal nella pipeline e nello stage Pipedrive che hai scelto, con lo slug del link, la sorgente UTM e un link diretto ad Elido nelle note del deal. Nessun Zapier nel mezzo, nessun export manuale, nessun promemoria in calendario per controllare i report dei link.

Questo è il titolo. La meccanica conta di più, quindi questo articolo percorre le tre cose che i team di sales ops devono capire prima di attivare questa funzione. Primo, come funziona davvero il flusso di Connect: dove vive il token API personale, cosa legge il selettore di pipeline, e come viene archiviato il token dopo averlo incollato. Secondo, cosa fa il cron delle soglie a ogni esecuzione e come evita di creare deal duplicati quando un link diventa virale da un giorno all'altro. Terzo, come estendere l'integrazione oltre le tre soglie predefinite, verso conteggi di clic personalizzati, trigger filtrati per UTM e campi Pipedrive personalizzati, usando il SDK di Elido e un piccolo handler webhook.

Pipedrive è diventato Live per Elido il 22 maggio 2026. Prima era rimasto due settimane in Beta mentre sistemavamo i casi limite attorno agli ID degli stage e alla rotazione dei token. Il codice dell'integrazione si trova in services/api-core/internal/integrations/pipedrive/ se ospiti autonomamente e vuoi leggere i sorgenti. Tutto in questo articolo corrisponde a ciò che è in produzione, non a una roadmap.

Connettere Pipedrive in due minuti

Apri il catalogo delle integrazioni nel tuo workspace Elido e clicca sulla card Pipedrive. La modal di connessione chiede prima una sola cosa: un token API personale. Lo ottieni dal tuo account Pipedrive aprendo il menu del profilo, scegliendo Preferenze personali e poi la scheda API. La guida ufficiale di Pipedrive su how to find the Personal API token mostra il percorso esatto con screenshot, dato che la loro interfaccia cambia circa ogni trimestre.

Incolla il token. Elido fa due cose in background. Valida il token chiamando GET /users/me contro la Pipedrive API, il che conferma che il token è attivo e ci dice a quale azienda Pipedrive appartiene. Recupera anche la lista delle pipeline e degli stage per quell'azienda, in modo che il passo successivo nella modal mostri opzioni reali e non campi di testo libero.

La modal pone poi altre due domande. In quale pipeline devono atterrare i nuovi deal? In quale stage di quella pipeline? I menu a tendina sono popolati dai tuoi dati Pipedrive in tempo reale. Se hai tre pipeline chiamate Inbound, Outbound e Partners, vedi quelle tre. Scegli quella adatta al lavoro - di solito Inbound per i segnali provenienti dal marketing - poi scegli il primo stage di qualificazione. Clicca su Connetti.

Cosa succede al token dopo la connessione. Elido lo cifra prima che raggiunga Postgres, usando cifratura a busta con una chiave di cifratura dati per tenant avvolta da una chiave KMS di workspace. Il blob cifrato è ciò che risiede nella tabella integration_credentials. Il token in chiaro esiste in memoria solo per la durata di una singola chiamata API, e non lo registriamo mai nei log, nemmeno a livello di debug. Se ruoti il token in Pipedrive, la prossima esecuzione del cron riceve un 401 e Elido contrassegna l'integrazione come da riautenticare, il che appare come un banner nel workspace, non come un fallimento silenzioso. L'igiene di rotazione spetta a te; il guasto è rumoroso.

Il selettore di pipeline è un dettaglio piccolo ma importante. Un modo frequente di fallire nelle integrazioni CRM è creare deal nella pipeline sbagliata perché l'integrazione fu costruita quando l'azienda aveva una pipeline e ora ne ha sei. Lasciare che l'utente scelga alla connessione, e mostrare la lista aggiornata invece di una cache di un mese fa, elimina tutta questa classe di errori. Puoi anche riconnetterti in qualsiasi momento per cambiare il target del selettore senza perdere la cronologia delle soglie.

Cosa fa davvero il cron di 5 minuti

In services/api-core c'è un job chiamato click_threshold_hook. Viene eseguito ogni cinque minuti. A ogni tick fa tre cose nell'ordine, per workspace con Pipedrive connesso.

Prima, chiede a ClickHouse i totali dei clic per link aggiornati negli ultimi sei minuti, più un buffer di un minuto per coprire gli eventi in ritardo. ClickHouse conserva gli eventi di clic in una tabella clicks partizionata per data, e il rollup che interroghiamo è una vista materializzata indicizzata per ID short link. La query restituisce i link i cui totali sono cambiati dall'ultima esecuzione del cron, non l'intera tabella. Su un workspace con 50.000 link attivi e un pattern di clic normale, questa query rimane sotto i 200 ms.

Secondo, confronta il nuovo totale di ogni link con le soglie registrate. Le soglie predefinite sono 100, 1.000 e 10.000. Per ogni link, Elido tiene traccia della soglia più alta mai raggiunta in una piccola riga link_threshold_state indicizzata per ID link. Se un link era a 80 clic nell'ultima esecuzione ed è ora a 240, il confronto mostra che la soglia di 100 è stata superata e quella di 1.000 non è ancora stata raggiunta. Segniamo 100 come raggiunta e mettiamo in coda una creazione di deal. Se un link è saltato da 80 a 1.200, sia 100 che 1.000 sono stati superati, quindi mettiamo in coda due creazioni.

Terzo, per ogni deal in coda, Elido chiama la Deals API di Pipedrive con un POST a /deals. Il body imposta l'ID pipeline e l'ID stage dal selettore di connessione, nomina il deal in modo leggibile come Link <slug> ha raggiunto <soglia> clic, e scrive la sorgente UTM, il medium e la campagna nella nota del deal insieme a un link cliccabile verso la vista analytics di Elido per quel link. Memorizziamo anche l'ID del link in un campo personalizzato Pipedrive se il workspace ne ha uno configurato, il che rende possibile interrogare Pipedrive in seguito per tutti i deal legati a uno specifico link Elido.

Alcune cose che questo cron non fa. Non riprova indefinitamente in caso di errori 5xx di Pipedrive. Se Pipedrive restituisce 500 o 503, riproviamo due volte con backoff esponenziale nello stesso tick del cron, poi lasciamo il lavoro al tick successivo. Il rate limit di Pipedrive è in pratica di 100 richieste per 2 secondi per token aziendale, il che lascia ampio margine per i volumi che la maggior parte dei team raggiungerà. Non creiamo nemmeno deal per link contrassegnati come test, interni, o di proprietà di un membro del workspace che ha disattivato la sincronizzazione CRM nelle proprie impostazioni personali.

La prevenzione dei duplicati è la parte che ha richiesto più iterazioni. La prima versione aveva una race condition: se due pod del cron giravano in sovrapposizione, entrambi potevano vedere lo stesso link superare 100 e entrambi potevano fare POST di un deal. L'abbiamo risolto con un advisory lock Postgres sull'ID workspace all'inizio di ogni tick del cron, più un vincolo univoco su (link_id, threshold) in link_threshold_state. Se il secondo pod tenta di inserire una riga duplicata, Postgres la rifiuta e il POST in coda viene scartato prima di raggiungere Pipedrive. Doppia protezione.

Andare oltre le tre soglie predefinite

Le soglie incluse sono 100, 1.000 e 10.000. La maggior parte dei team le mantiene perché si adattano naturalmente a una narrativa di vendita. Cento clic sono un segnale debole che merita uno sguardo. Mille è una campagna che vale una chiamata. Diecimila è abbastanza caldo da aspettarsi che un commerciale sia già in azione. Detto questo, potresti volere numeri diversi, e il SDK lo supporta.

L'integrazione Pipedrive di Elido accetta un elenco di soglie personalizzato a livello di workspace. Lo si imposta tramite l'endpoint PATCH /v1/workspaces/:id/integrations/pipedrive con un corpo JSON come {"thresholds": [50, 500, 5000, 50000]}. Il cron prende il nuovo elenco al tick successivo. La tabella di stato conserva la cronologia, quindi modificare le soglie non crea deal retroattivamente, cambia solo quali attraversamenti futuri attivano un evento.

Per trigger più ricchi, il SDK espone un hook CreateDeal che puoi registrare da qualsiasi servizio. Il caso classico: creare un deal solo quando un link supera una soglia E la sorgente UTM è la tua campagna social a pagamento, non il tuo blog organico. Questo è un filtro di una riga all'interno dell'hook. Un altro caso comune: attivare solo sui link all'interno di una specifica cartella Elido, perché quella cartella è la tua cartella di campagna e tutto il resto è rumore. Lo stesso hook può anche impostare campi personalizzati Pipedrive come Fonte del Deal, Canale Lead, o qualsiasi tassonomia usi il tuo team di sales ops. La guida al forwarding delle conversioni copre lo stesso pattern di hook per le piattaforme pubblicitarie; il caso Pipedrive è strutturalmente identico.

Una nota sui campi personalizzati. Il SDK accetta sia l'etichetta leggibile dall'uomo sia la chiave API con hash che Pipedrive usa internamente. Se fai riferimento a un'etichetta che non esiste nell'azienda connessa, il deal viene comunque creato e il campo mancante viene registrato come avviso, mai come errore. Un campo personalizzato mancante non dovrebbe bloccare un vero segnale di vendita.

I team con molti link per campagna vogliono a volte aggregare le soglie su una cartella. Imposta aggregation: "folder" nella configurazione dell'integrazione del workspace e il cron raggruppa i totali dei clic per cartella, poi controlla la somma. Il deal nomina la cartella e lista i tre link con il contributo maggiore nelle note.

Dove vive il token e come ruotarlo

Una sezione breve perché viene fuori in ogni revisione di sicurezza. Il token API personale è cifrato a riposo usando AES-256-GCM con una chiave di cifratura dati per tenant. La DEK è a sua volta avvolta da una chiave a livello di workspace nel nostro KMS, e solo il processo api-core può disimpastarla. Non c'è alcun token in chiaro in nessun log, backup o traccia di errore. L'abbiamo testato con un'iniezione di guasto che ha forzato un 401 di Pipedrive a metà richiesta, e il percorso di errore elimina il token dalla risposta prima che raggiunga Sentry.

Per ruotare: genera un nuovo token API personale in Pipedrive, revoca quello vecchio, poi incolla il nuovo nella modal di connessione di Elido. L'integrazione valida il nuovo token, lo sostituisce, e il prossimo tick del cron lo usa. Se dimentichi di aggiornare Elido dopo aver revocato il vecchio token, il prossimo tick del cron riceve un 401 e l'integrazione entra in uno stato di Riautenticazione necessaria, visibile come un banner giallo sul dashboard del workspace. Nessun token morto silenzioso.

Con il self-host il KMS è configurabile: basato su file per impostazione predefinita, puoi sostituirlo con HashiCorp Vault o il tuo KMS cloud. ADR-0036 copre i dettagli.

Come si inserisce in un funnel più ampio

I trigger di deal Pipedrive dai clic sono un pezzo di un pattern più grande. I conteggi dei clic sono un indicatore anticipatore, non un numero di fatturato, quindi di solito vuoi che fluiscano in un CRM dove vive il resto del contesto di vendita. Il deal è il passaggio di consegne: il marketing ha fatto il suo lavoro, le vendite lo raccolgono. Da lì i tuoi normali workflow Pipedrive prendono il sopravvento: assegnare il deal a un commerciale, valutarlo, farlo avanzare attraverso gli stage, chiuderlo.

Se stai anche inoltrando conversioni alle piattaforme pubblicitarie, gli stessi dati di clic alimentano entrambi i flussi. La funzione di tracciamento delle conversioni gestisce il lato pubblicità, l'integrazione Pipedrive gestisce il lato CRM, e le due non si contendono mai lo stesso evento. Vediamo questa combinazione più spesso nella pagina delle soluzioni per i marketer, dove l'intero stack va dall'acquisizione a pagamento attraverso link con brand a un funnel CRM.

Per gli analisti che vogliono mantenere i loro numeri onesti, due articoli precedenti coprono le preoccupazioni a monte. Short link analytics: what to measure copre quali metriche di clic correlano davvero con i ricavi, e Track UTM end to end copre l'igiene UTM che rende le note del deal utili invece che rumorose. Entrambi si abbinano bene a questa integrazione, poiché il deal che Pipedrive crea è utile solo quanto i dati UTM che porta.

Un ultimo dettaglio sui piani. L'integrazione Pipedrive è disponibile su ogni livello Elido a pagamento, e la prova di 14 giorni la include per permetterti di validare il tuo elenco di soglie prima di sottoscrivere. I workspace gratuiti possono creare la connessione per i test, ma il cron non si attiva per i link gratuiti. La pagina dei prezzi riporta il dettaglio per livello.

Checklist di configurazione

Stampala, eseguila una volta.

1. In Pipedrive: menu del profilo, Preferenze personali, scheda API, copia il token.
2. In Elido: Integrazioni, card Pipedrive, Connetti.
3. Incolla il token. Attendi la validazione.
4. Scegli la pipeline e lo stage. Predefinito: Inbound e il primo stage di qualificazione.
5. Clicca su Connetti.
6. Opzionale: modifica l'elenco delle soglie se 100/1k/10k non si adatta al tuo processo di vendita.
7. Opzionale: registra un hook CreateDeal personalizzato per filtri UTM o aggregazioni di cartelle.
8. Attendi cinque minuti. Invia alcuni clic di test. Osserva l'arrivo del primo deal.

Tutto qui. Se esegui il self-host, dovrai anche verificare che il cron sia abilitato controllando che kubectl get cronjob api-core-click-threshold-hook restituisca un piano attivo. Su Elido Cloud il cron è gestito per te.