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

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

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

OAuth в один клік: що насправді відбувається, коли ви натискаєте Connect

Старі процеси зі вставлянням токена вимагали згенерувати внутрішній токен інтеграції Notion, вставити його, а потім вручну поділитися кожною базою даних з інтеграцією. Цього більше немає. Новий процес - три кліки: Connect в Elido, вибір робочого простору й баз даних на екрані згоди Notion, готово. Танець OAuth слідує стандарту з документації Notion API щодо автентифікації. Notion не підтримує PKCE, тож обмін - це звичайний потік authorization code, захищений параметром state.

У Notion немає вибору окремих прав доступу під час авторизації; можливості встановлюються на боці інтеграції Elido, а ви обираєте, які сторінки і бази даних вона бачитиме. Ці можливості навмисно вузькі:

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

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

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

Кнопка підключення живе на вкладці Integrations для кожного робочого простору, так само як і в будь-якого іншого постачальника в каталозі інтеграцій. На сторінці інтеграції з Notion є скріншот екрана згоди. Дозволи можна відкликати на панелі Settings, Connections у Notion; Disconnect в Elido позначає з'єднання як відкликане на боці Elido.

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

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

Карта полів: шість стовпців і чому вони саме такі

Усе від цього місця до покрокового розбору налаштування описує заплановану синхронізацію, а не те, що працює сьогодні. Сьогодні підключення дозволяє Elido перелічувати ваші спільні бази даних і створювати в них рядки через клієнт API.

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

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

Кілька рішень варто пояснити окремо.

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

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

Tags двосторонній з об'єднанням множин. Єдиний стовпець, куди пишуть обидві сторони. Позначте рядок тегом «launch-2026» у Notion, 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, у тому самому п'ятихвилинному вікні. Notion володіє Destination, тож Notion перемагає. Elido відкидає запис від Zap, публікує коментар до рядка («Конфлікт Destination о 14:02:30, збережено значення Notion, див. журнал аудиту») і випускає подію конфлікту, на яку можна підписатися через вебхуки. Zap слухає і вирішує, чи повторити спробу, чи надіслати сповіщення.

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

Коли зміна пункту призначення НЕ повинна поширюватися

Іноді ви редагуєте Destination як чернетку. Тут допомагають два патерни.

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

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

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

Крок 1 працює вже сьогодні. Кроки 2-5 з'являться разом із запланованою синхронізацією.

1. Підключіть Notion. Workspace settings, Integrations, Notion, Connect. Оберіть робочий простір, відмітьте бази даних, Allow.
2. Оберіть базу даних. Settings, Notion, «Add database». Випадний список показує кожну базу даних, до якої ви надали доступ. Оберіть одну.
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.

Усунення несправностей: чотири проблеми, з якими ми зіткнулися в Beta

Під час Beta виявилося чотири класи проблем. Кілька з них стосуються запланованої синхронізації, а не активного підключення, але корисно знати, на що звертати увагу.

«Database not found» після перейменування робочого простору. Якщо адміністратор Notion перейменовує робочий простір, ID робочого простору залишається стабільним, але кешовані метадані застарівають на нашому боці до однієї години. Обхідний шлях: натисніть «Force re-sync» у Settings, Notion. TTL кешу в продакшені встановлено на 15 хвилин, тож це здебільшого артефакт Beta.

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

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

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

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

Що на черзі далі

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

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