Відстеження кліків Pipedrive: угоди з переходів за короткими посиланнями

Відстеження кліків Pipedrive в Elido перетворює віхи коротких посилань на події воронки. Коли одне з ваших посилань досягає 100, 1000 або 10 000 кліків, cron, що запускається кожні 5 хвилин, створює угоду у вибраних воронці та етапі Pipedrive - зі слагом посилання, джерелом UTM і прямим посиланням назад до Elido в нотатках до угоди. Без Zapier посередині, без ручного експорту, без нагадування в календарі перевірити звіти за посиланнями.

Це заголовок. Механіка важливіша, тому ця стаття розглядає три речі, які команди sales ops мають зрозуміти перед увімкненням функції. По-перше, як насправді працює процес підключення: де зберігається особистий токен API, що зчитує вибір воронки і як токен зберігається після вставки. По-друге, що робить cron порогів при кожному запуску і як він запобігає створенню дублюючих угод, коли посилання за ніч стає вірусним. По-третє, як розширити інтеграцію за межі трьох стандартних порогів - до довільних значень кліків, тригерів з фільтрацією по UTM і користувацьких полів Pipedrive - за допомогою Elido SDK і невеликого обробника webhook.

Pipedrive перейшов у статус Live для Elido 22 травня 2026 року. До цього два тижні він перебував у Beta, поки ми усували граничні випадки, пов'язані з ID етапів і ротацією токенів. Код інтеграції знаходиться в services/api-core/internal/integrations/pipedrive/, якщо ви використовуєте самостійний хостинг і хочете вивчити джерела. Все в цій статті відповідає тому, що вже випущено, а не дорожній карті.

Підключення Pipedrive за дві хвилини

Відкрийте каталог інтеграцій у робочому просторі Elido і натисніть на картку Pipedrive. Модальне вікно Connect спочатку запитує одне: особистий токен API. Його можна отримати в акаунті Pipedrive, відкривши меню профілю, вибравши «Особисті налаштування», а потім вкладку API. В офіційному посібнику Pipedrive щодо how to find the Personal API token є точний шлях зі скриншотами - їхній інтерфейс змінюється приблизно раз на квартал.

Вставте токен. Elido виконує у фоні дві дії. Перевіряє токен, викликаючи GET /users/me у Pipedrive API, що підтверджує активність токена і повідомляє, до якої компанії Pipedrive він належить. Також завантажує список воронок і етапів для цієї компанії, щоб наступний крок у модальному вікні показував реальні варіанти, а не поля вільного введення.

Потім модальне вікно ставить ще два запитання. До якої воронки мають потрапляти нові угоди? На якому етапі цієї воронки? Випадаючі списки заповнюються з ваших актуальних даних Pipedrive. Якщо у вас три воронки з назвами Inbound, Outbound і Partners, ви побачите саме їх. Виберіть відповідну - зазвичай Inbound для сигналів від маркетингу - і перший кваліфікаційний етап. Натисніть «Підключити».

Що відбувається з токеном після підключення. Elido шифрує його ще до запису в Postgres, використовуючи конвертне шифрування з ключем шифрування даних на рівні орендаря, що обгорнутий ключем KMS робочого простору. В таблиці integration_credentials зберігається саме цей зашифрований blob. Токен у відкритому вигляді існує в пам'яті лише на час одного виклику API і ніколи не потрапляє в логи - навіть на рівні debug. Якщо ви ротуєте токен у Pipedrive, наступний запуск cron отримає 401, і Elido позначить інтеграцію як таку, що потребує повторної автентифікації - це відображається банером у робочому просторі, а не тихим збоєм. Гігієна ротації - ваша відповідальність; при проблемі буде явне сповіщення.

Вибір воронки - невелика, але важлива деталь. Поширений сценарій відмови в інтеграціях CRM: угоди створюються не в тій воронці, бо інтеграцію налаштували, коли у компанії була одна воронка, а тепер їх шість. Надання користувачу можливості вибору при підключенні і показ актуального списку замість кешу місячної давності усуває цілий клас помилок. Ви також можете в будь-який момент перепідключитися, щоб змінити цільову воронку, не втративши історію порогів.

Що насправді робить cron кожні 5 хвилин

У services/api-core є задача з назвою click_threshold_hook. Вона запускається кожні п'ять хвилин. При кожному тіку вона послідовно виконує три операції для кожного робочого простору з підключеним Pipedrive.

Перше: запитує у ClickHouse сумарні кліки по посиланнях, оновлені за останні шість хвилин, плюс буфер в одну хвилину для врахування запізнілих подій. ClickHouse зберігає події кліків у таблиці clicks, партиціонованій за датою, а запитуваний rollup - це матеріалізоване представлення з ключем по ID короткого посилання. Запит повертає лише посилання, чиї суми змінились з попереднього запуску cron, а не всю таблицю. На робочому просторі з 50 000 активними посиланнями при звичайному патерні кліків цей запит виконується менш ніж за 200 мс.

Друге: порівнює новий підсумок кожного посилання із зафіксованими порогами. Стандартні пороги - 100, 1000 і 10 000. Для кожного посилання Elido зберігає найвищий досягнутий поріг у невеликому рядку link_threshold_state з ключем по ID посилання. Якщо при попередньому запуску посилання мало 80 кліків, а тепер 240, порівняння показує, що поріг 100 перетнуто, а 1000 ще ні. Ми позначаємо 100 як досягнутий і ставимо одне створення угоди в чергу. Якщо посилання стрибнуло з 80 до 1200 - перетнуті і 100, і 1000, тому в чергу ставляться два створення.

Третє: для кожної угоди в черзі Elido викликає Deals API Pipedrive з POST на /deals. Тіло запиту встановлює ID воронки та ID етапу з налаштувань підключення, задає читабельну назву угоди на кшталт Посилання <слаг> досягло <поріг> кліків і записує джерело UTM, медіум і кампанію в нотатку до угоди разом з клікабельним посиланням на аналітику цього посилання в Elido. Ми також зберігаємо ID посилання в користувацьке поле Pipedrive, якщо воно налаштоване в робочому просторі, - це дозволяє пізніше запитувати в Pipedrive всі угоди, пов'язані з конкретним посиланням Elido.

Кілька речей, яких цей cron не робить. Він не повторює спроби нескінченно при помилках 5xx Pipedrive. Якщо Pipedrive повертає 500 або 503, ми робимо дві повторні спроби з експоненційною затримкою в рамках того ж тіку, а потім залишаємо роботу наступному тіку. Ліміт запитів Pipedrive на практиці становить 100 запитів за 2 секунди на корпоративний токен - цього з запасом вистачає для обсягів більшості команд. Ми також не створюємо угоди для посилань, позначених як тестові, внутрішні або таких, що належать учаснику робочого простору, який відключив синхронізацію CRM в особистих налаштуваннях.

Запобігання дублям вимагало найбільшої кількості ітерацій. У першій версії була гонка станів: якщо два поди cron працювали одночасно, обидва могли побачити одне посилання, що перетинає 100, і обидва робили POST угоди. Ми вирішили це за допомогою advisory lock Postgres на ID робочого простору на початку кожного тіку cron, а також унікального обмеження на (link_id, threshold) у link_threshold_state. Якщо другий под спробує вставити дублюючий рядок, Postgres відхилить його, і POST з черги буде відкинуто ще до звернення до Pipedrive. Подвійна страховка.

Розширення за межі трьох стандартних порогів

Вбудовані пороги - 100, 1000 і 10 000. Більшість команд їх зберігають, оскільки вони природно вписуються в логіку продажів. Сто кліків - слабкий сигнал, що варто уваги. Тисяча - кампанія, яка заслуговує на дзвінок. Десять тисяч - достатньо гарячий сигнал, щоб менеджер вже діяв. Водночас вам можуть знадобитися інші значення, і SDK це підтримує.

Інтеграція Pipedrive в Elido приймає користувацький список порогів на рівні робочого простору. Його задають через endpoint PATCH /v1/workspaces/:id/integrations/pipedrive з тілом JSON виду {"thresholds": [50, 500, 5000, 50000]}. Cron підхоплює новий список при наступному тіку. Таблиця стану зберігає історію, тому зміна порогів не створює угоди ретроактивно - вона змінює лише те, які майбутні перетини будуть спрацьовувати.

Для складніших тригерів SDK надає хук CreateDeal, який можна зареєструвати з будь-якого сервісу. Класичний випадок: створювати угоду лише тоді, коли посилання перетинає поріг І джерело UTM - ваша платна соціальна кампанія, а не органічний блог. Це однорядковий фільтр всередині хука. Інший поширений випадок: спрацьовувати лише на посиланнях всередині конкретної папки Elido, бо саме там знаходяться посилання кампанії, а решта - шум. Той самий хук може встановлювати користувацькі поля Pipedrive, такі як «Джерело угоди», «Канал ліда» або будь-яку таксономію, прийняту у вашій команді sales ops. У посібнику з переадресації конверсій описано той самий патерн хука для рекламних платформ - випадок з Pipedrive структурно ідентичний.

Зауваження щодо користувацьких полів. SDK приймає як читабельну мітку, так і захешований API-ключ, який Pipedrive використовує внутрішньо. Якщо ви посилаєтесь на мітку, якої немає в підключеній компанії, угода все одно створюється, а відсутнє поле логується як попередження, а не помилка. Відсутнє користувацьке поле не повинно блокувати реальний сигнал продажів.

Команди з великою кількістю посилань на кампанію іноді хочуть агрегувати пороги по папці. Вкажіть aggregation: "folder" у конфігурації інтеграції робочого простору, і cron групуватиме сумарні кліки по папках, перевіряючи загальну суму. Назва угоди включає папку, а в нотатках перелічені три посилання з найбільшим внеском.

Де зберігається токен і як його ротувати

Короткий розділ, який виникає на кожній перевірці безпеки. Особистий токен API шифрується в стані спокою з використанням AES-256-GCM з ключем шифрування даних на рівні орендаря. Сам DEK обгорнутий ключем рівня робочого простору в нашому KMS, і лише процес api-core може його розгорнути. Токена у відкритому вигляді немає ні в жодному лозі, резервній копії чи трасуванні помилок. Ми перевіряли це за допомогою впровадження помилки, що примусово викликала 401 від Pipedrive посередині запиту, і шлях обробки помилки очищає токен з відповіді ще до того, як вона потрапить у Sentry.

Для ротації: згенеруйте новий особистий токен API в Pipedrive, відкличте старий, потім вставте новий у модальне вікно Connect в Elido. Інтеграція перевірить новий токен, замінить його на місці, і наступний тік cron використовуватиме його. Якщо ви забудете оновити Elido після відкликання старого токена, наступний тік cron отримає 401, і інтеграція перейде в стан «Потрібна повторна автентифікація» - видимий як жовтий банер на панелі робочого простору. Жодних тихих мертвих токенів.

При самостійному хостингу KMS підключається через плагін: за замовчуванням на основі файлів, але можна замінити на HashiCorp Vault або хмарний KMS. ADR-0036 містить подробиці.

Як це вписується в ширшу воронку

Тригери угод Pipedrive по кліках - частина ширшого патерну. Кількість кліків - це випереджальний індикатор, а не цифра виручки, тому зазвичай потрібно направити їх у CRM, де живе решта контексту продажів. Угода - це передача естафети: маркетинг виконав свою роботу, продажі її підхоплюють. Далі вступають ваші стандартні робочі процеси Pipedrive: призначення угоди менеджеру, оцінка, просування по етапах, закриття.

Якщо ви також переадресовуєте конверсії на рекламні платформи, одні й ті самі дані кліків живлять обидва потоки. Функція відстеження конверсій обробляє рекламну сторону, інтеграція Pipedrive - сторону CRM, і вони ніколи не конкурують за одну й ту саму подію. Ця комбінація найчастіше зустрічається на сторінці рішень для маркетологів, де весь стек - це платне залучення через брендовані посилання у CRM-воронку.

Для аналітиків, які хочуть зберігати точність чисел, два попередніх матеріали охоплюють питання вище по потоку. Short link analytics: what to measure - про те, які метрики кліків реально корелюють з виручкою, Track UTM end to end - про гігієну UTM, яка робить нотатки до угод корисними, а не зашумленими. Обидва добре поєднуються з цією інтеграцією, оскільки угода, яку створює Pipedrive, є настільки корисною, наскільки повними є UTM-дані, що вона несе.

Останнє уточнення щодо планів. Інтеграція Pipedrive доступна на кожному платному рівні Elido, а 14-денний пробний період включає її, щоб ви могли перевірити список порогів до підписки. Безкоштовні робочі простори можуть створити підключення для тестування, але cron не спрацьовує для безкоштовних посилань. На сторінці тарифів є розбивка по рівнях.

Чек-лист налаштування

Роздрукуйте, виконайте один раз.

1. У Pipedrive: меню профілю, «Особисті налаштування», вкладка API, скопіювати токен.
2. В Elido: «Інтеграції», картка Pipedrive, «Підключити».
3. Вставити токен. Дочекатися перевірки.
4. Вибрати воронку та етап. За замовчуванням: Inbound і перший кваліфікаційний етап.
5. Натиснути «Підключити».
6. Опціонально: відредагувати список порогів, якщо 100/1k/10k не відповідає вашому процесу продажів.
7. Опціонально: зареєструвати власний хук CreateDeal для фільтрації по UTM або агрегації по папках.
8. Почекати п'ять хвилин. Надіслати кілька тестових кліків. Переконатися, що з'явилась перша угода.

Ось і все. При самостійному хостингу також перевірте, що cron увімкнено: kubectl get cronjob api-core-click-threshold-hook має повертати активний розклад. У Elido Cloud cron управляється за вас.