Інтеграція скорочувача URL з Notion: OAuth + двостороння синхронізація бази даних

Інтеграція скорочувача URL з Notion перейшла з бета-версії до статусу Live 4 червня 2026 року. Якщо ви використовуєте Notion як центр управління кампаніями, Elido читає URL з будь-якої обраної бази даних, створює брендовані короткі посилання на вашому домені, записує їх назад до таблиці і відстежує зміни цільових адрес. Одне натискання через OAuth, жодного копіювання токенів вручну, а зіставлення полів налаштовується окремо для кожної бази даних.

У цій статті розглядається крок підключення через OAuth з дозволами, структура із шести стовпців і двосторонній потік редагування з вирішенням конфліктів. Якщо ви читали попереднє введення у короткі посилання з Notion, перед вами - поглиблений аналіз теми.

OAuth одним кліком: що насправді відбувається при натисканні «Підключити»

Старі процеси на основі вставки токенів вимагали вручну створити внутрішній токен інтеграції Notion, вставити його, а потім окремо поділитися кожною базою даних з інтеграцією. Це вже в минулому. Новий процес - три кліки: «Підключити» в Elido, вибрати робочий простір і бази даних на екрані підтвердження Notion, готово. Обмін OAuth відповідає стандарту з документації з автентифікації API Notion з використанням PKCE при обміні коду авторизації.

Надані дозволи навмисно обмежені:

• read_content - читання властивостей Destination, Tags і Title у вибраних базах даних.
• insert_content - створення нових рядків, коли ви просите Elido створити посилання із зовнішнього джерела (Zap, webhook, CSV).
• update_content - зворотний запис властивостей Short URL, Clicks, QR і Last Synced.

Elido ніколи не запитує доступ на читання всього робочого простору та не запитує сторінки, які ви не відмітили. Notion також перевіряє це на стороні сервера: запит до бази даних поза межами дозволів повертає 403. Довідник API Notion для операцій з базами даних описує методи, що використовуються інтеграцією.

Після завершення підтвердження браузер переходить на api.elido.app/v1/oauth/notion/callback з кодом авторизації. api-core обмінює код на токен доступу, шифрує токен ключем KMS робочого простору (відповідно до ADR-0036) і зберігає його в integration_credentials. Токен у відкритому вигляді ніколи не потрапляє на диск або до логів. До журналу аудиту також додається запис, щоб адміністратор міг бачити, хто і коли підключив те чи інше робоче середовище Notion.

Кнопка підключення знаходиться у вкладці «Інтеграції» кожного робочого простору - так само, як і для будь-якого іншого постачальника у каталозі інтеграцій. На сторінці інтеграції з Notion є знімок екрана підтвердження. Дозволи можна відкликати в Налаштуваннях Notion, розділ «З'єднання» - відкликання там запускає webhook, який видаляє токен на стороні Elido протягом 60 секунд.

Два режими: приєднати або створити

У режимі приєднання ви вказуєте Elido на існуючу базу даних із властивістю URL. Elido додає лише необхідні стовпці, не перейменовуючи нічого. У режимі створення Elido створює нову базу даних «Elido Links» всередині обраної сторінки. Більшість команд обирають режим приєднання, оскільки їхня таблиця кампаній вже існує з даними за кілька кварталів. В обох випадках схема однакова.

Зіставлення полів: шість стовпців і логіка їх побудови

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

Стовпець	Тип у Notion	Напрямок	Примітки
Short URL	URL	Elido записує	Лише для читання з боку користувача; редагування не дає ефекту.
Destination	URL	Notion записує	Цільова адреса, на яку вказує коротке посилання. Редагується.
Tags	Мультивибір	Двосторонній	Теги об'єднуються через об'єднання множин при конфлікті.
Clicks	Число	Elido записує	Опитується кожні 5 хвилин. Лише для читання.
QR	Файли	Elido записує	PNG розміром 1024px з QR-кодом для короткого посилання.
Last Synced	Дата	Elido записує	Мітка часу UTC останньої синхронізації.

Кілька рішень заслуговують на окреме пояснення.

Clicks навмисно не оновлюється в реальному часі. У Notion немає потокових примітивів, а звернення до їхнього ендпоінта при кожному кліку швидко вичерпає ліміт запитів. П'ять хвилин відповідає актуальності, необхідній більшості операційних команд. Для реального часу запустіть webhook на події кліків за посиланнями і направте його до власного дашборду. Notion - це представлення кампанії; webhook - це безперервний потік даних.

QR - це властивість типу «Файли», а не URL. Notion не відображає зовнішні URL зображень у таблицях, але прикріплені файли показуються як мініатюри. Elido завантажує PNG при першій синхронізації і повторно завантажує його лише при зміні короткого посилання. Дивіться сторінку функції QR-кодів і посібник з QR GS1.

Tags - двосторонній з об'єднанням множин. Єдиний стовпець, до якого записують обидві сторони. Позначте рядок у Notion тегом «launch-2026», у Elido є «winter-promo» із Zap - при наступній синхронізації обидва теги існують з обох боків. Видалення також поширюються. Журнал аудиту фіксує кожну зміну.

Для UTM-параметрів посібник з шаблонів UTM дозволяє прив'язати шаблон до папки, щоб кожне посилання успадковувало правильний utm_source. Стовпець Destination залишається чистим, а Elido додає параметри в момент вирішення кліку через правила розумних посилань.

Двосторонній потік редагування: хто перемагає, коли Notion і Elido розходяться

Саме цей розділ найбільше цікавить команди, адже у інструментів синхронізації є історія прихованих перезаписів. Ось умови контракту.

Воркер усередині api-core опитує кожну підключену базу даних кожні п'ять хвилин у пошуках змін з моменту останнього водяного знака last_edited_time. При зміні властивості він завантажує зіставлення полів і визначає власника. Правила фіксовані:

• Notion володіє: Destination, Tags (сторона запису), Title.
• Elido володіє: Short URL, Clicks, QR, Last Synced.
• Спільне: Tags (сторона читання; обидві сторони бачать об'єднаний набір).

Якщо властивість, що належить Notion, змінилася у Notion, Elido оновлює внутрішній стан і генерує подію integration.notion.sync. Якщо властивість, що належить Elido, змінилася (оновлення лічильника кліків), Elido записує її назад при наступній синхронізації.

Цікавий випадок - колізія. Припустимо, ви змінили Destination у Notion о 14:02:10, а Zap записав нову Destination в Elido о 14:02:30, в тому самому п'ятихвилинному вікні. Destination належить Notion, тому Notion перемагає. Elido відкидає запис Zap, додає коментар до рядка («Конфлікт Destination о 14:02:30, збережено значення Notion, дивіться журнал аудиту») і генерує подію конфлікту, на яку можна підписатися через webhooks. Zap слухає і вирішує, повторити спробу чи надіслати сповіщення.

Ніде немає прихованих перезаписів. Кожен запис фіксується. Кожен конфлікт отримує коментар до рядка. Для постійного запису направте потік аудиту до сховища даних через посібник з експорту в ClickHouse або звертайтесь безпосередньо до GraphQL API.

Коли зміна цільової адреси НЕ повинна поширюватися

Іноді ви редагуєте цільову адресу як чернетку. Два патерни допомагають у цьому випадку.

Властивість «Статус» як охоронець. Додайте поле типу «Вибір» із назвою «Sync» зі значеннями Draft, Live, Paused. Інтеграція синхронізує лише рядки, де Sync = Live. Працюйте в Draft, переключайтесь на Live - наступний тік підбере зміну. Більшість маркетингових команд зрештою використовують саме цей підхід.

Призупинити всю базу даних. Налаштування, Notion, пауза для конкретної бази даних. Зручно під час міграції або масового редагування.

Покрокове налаштування: від нуля до першого синхронізованого рядка за 4 хвилини

1. Підключити Notion. Налаштування робочого простору, Інтеграції, Notion, Підключити. Виберіть робочий простір, відмітьте бази даних, Дозволити.
2. Вибрати базу даних. Налаштування, Notion, «Додати базу даних». У спадному списку відображаються всі дозволені бази даних. Виберіть одну.
3. Зіставити поля. Підтвердьте Destination, Title і решту. Не вистачає властивостей? Elido запропонує їх створити.
4. Вибрати домен. Виберіть брендований домен для коротких посилань. Ще немає власного домену? Оберіть стандартний - міграція буде доступна одним кліком пізніше.
5. Зберегти і заповнити. Elido читає кожен рядок, генерує коротке посилання для рядків із Destination, але без Short URL, і записує результати назад. Наявні Short URL залишаються без змін.

Реальний час - близько 4 хвилин для 200 рядків. При більшому заповненні спрацьовує обмеження Notion у три запити на секунду для безкоштовних робочих просторів. База даних із 5000 рядків заповнюється приблизно за 30 хвилин; воркер обробляє пакетами і самостійно відновлює роботу при обмеженні швидкості.

Коли використовувати це замість Zapier або прямого API

Існують три варіанти, що не виключають один одного.

Нативна інтеграція - правильний вибір за замовчуванням, якщо Notion є робочим майданчиком. OAuth, вирішення конфліктів, журнал аудиту, зіставлення полів, без написання коду.

Zap підходить для багатоетапних робочих процесів («коли додається рядок І приходить реакція у Slack, створити посилання»). Для прямого зіставлення рядка з посиланням нативна інтеграція швидша і дешевша. Дивіться статтю про автоматизацію з Zapier.

REST API підходить для побудови власного робочого процесу поверх Elido. Для розробників, що створюють продуктові інтеграції, вихідний код у services/api-core/internal/integrations/notion/ достатньо компактний, щоб прочитати його за одну сесію.

Порівняно з Bitly або Rebrandly: на момент написання жоден із них не має нативної інтеграції з Notion. Обидва вимагають Zapier або власного скрипту. Дивіться сторінку vs Bitly для порівняння і сторінку тарифів для інформації про плани з необмеженими базами даних Notion.

Усунення неполадок: чотири проблеми з бета-тестування

За вісім тижнів бета-тестування виявилися чотири категорії проблем. Усі вони вже усунені в коді, але корисно знати, на що звертати увагу.

«База даних не знайдена» після перейменування робочого простору. Якщо адміністратор Notion перейменовує робочий простір, його ID залишається стабільним, але кешовані метадані застарівають на нашому боці на строк до години. Обхідний шлях: натисніть «Примусова повторна синхронізація» в Налаштування, Notion. TTL кешу у production становить 15 хвилин, тому це переважно артефакт бета-версії.

Обмеження швидкості при великому заповненні. Ліміт Notion на одну інтеграцію - три запити на секунду. База даних із 5000 рядків сильно упирається в цей ліміт при початковому заповненні. Воркер застосовує експоненціальний backoff (250 мс, 500 мс, 1 с, 2 с, максимум 8 с) і відновлює роботу. У журналі активності з'явиться «Throttled by Notion, resuming» - це нормально.

Невідповідність типу властивості. Найпоширеніша проблема в беті. Користувач вибрав для Destination стовпець Notion типу «Текст» замість «URL». Валідатор зіставлення полів тепер фіксує це при збереженні і відмовляється продовжувати. Якщо ви бачите «Destination має бути властивістю URL», спочатку змініть тип стовпця у Notion.

Користувач кількох робочих просторів зі спільними базами даних. Якщо одна і та сама особа є учасником двох робочих просторів Notion і обидва хочуть підключити Elido, кожному робочому простору потрібен власний дозвіл OAuth. Токен прив'язаний до робочого простору, а не до користувача. Процес підключення обробляє це коректно; просто очікуйте, що доведеться натиснути «Підключити» двічі.

Для всього, чого немає в цьому списку, сторінка контактів веде безпосередньо до команди інтеграцій. Проблеми помічаються там швидше, ніж у загальній підтримці.

Що буде далі

У дорожній карті два пункти. Рецепт «форма Notion у коротке посилання», щоб відправлення форми створювало відстежуване посилання. І двостороння синхронізація властивості Workspace, щоб посилання могло слідувати при переміщенні рядка між базами даних. Обидва заплановані на Q3; відмітимо їх у changelog.

Для вимірювання результатів вступний посібник з аналітики коротких посилань пояснює, які метрики дійсно важливі і як налаштувати рядки дашборду Notion, щоб вони відповідали на правильні питання.