Интеграция Notion с сокращением ссылок: OAuth и двусторонняя синхронизация базы данных

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

В этой статье описан шаг подключения через OAuth, который уже работает, а затем запланированная структура из шести колонок и процесс двусторонней синхронизации с разрешением конфликтов. Если вы читали более раннюю статью про короткие ссылки в Notion, это более глубокий разбор.

OAuth в один клик: что на самом деле происходит при нажатии Connect

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

У Notion нет выбора отдельных прав доступа на этапе авторизации; возможности задаются на стороне интеграции Elido, а вы выбираете, какие страницы и базы данных она может видеть. Возможности намеренно узкие:

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

Elido никогда не запрашивает чтение всего рабочего пространства или страниц, которые вы не отметили. Notion тоже обеспечивает это на стороне сервера: запрос к базе данных вне выданного разрешения возвращает 403. Справочник API Notion по операциям с базами данных описывает методы, которые использует интеграция.

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

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

Два режима: подключение или создание

В режиме подключения (attach) вы указываете Elido на существующую базу данных со свойством URL. Elido добавляет только необходимые колонки (и ничего лишнего), не переименовывая ничего. В режиме создания (create) 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 размером 1024 пикселя с QR-кодом для короткой ссылки.
Last Synced	Date	Пишет Elido	Временная метка UTC последнего касания синхронизации.

Пара решений, которые стоит пояснить отдельно.

Clicks намеренно не в реальном времени. У Notion нет примитива потоковой передачи, а долбить их endpoint на каждый клик сожгло бы лимит запросов. Пять минут соответствуют той свежести данных, которая нужна большинству операционных команд. Для реального времени событие вебхука на каждый клик стоит в roadmap; пока его нет, берите клики из 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 добавляет параметры в момент разрешения клика через правила smart link.

Двусторонняя синхронизация: кто побеждает, когда 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, см. журнал аудита») и генерирует событие конфликта, на которое можно подписаться через вебхуки. Zap слушает это событие и решает, повторить попытку или отправить оповещение.

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

Когда изменение адреса назначения НЕ должно распространяться

Иногда вы редактируете Destination как черновик. Помогают два паттерна.

Свойство статуса как защита. Добавьте 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. Сохраните и запустите backfill. Elido читает каждую строку, создает короткую ссылку для тех, где есть Destination, но нет Short URL, и записывает результат обратно. Существующие Short URL не трогает.

По факту это занимает около 4 минут на 200 строк. Более крупные backfill-и упираются в лимит Notion в три запроса в секунду на бесплатных рабочих пространствах. База данных из 5000 строк заполняется примерно за 30 минут; воркер разбивает работу на пакеты и сам возобновляет ее при ограничении по скорости.

Когда использовать это, а когда Zapier или API напрямую

Существуют три пути, не исключающие друг друга.

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

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

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

Сравнивая с Bitly или Rebrandly: на момент написания ни у одного из них нет нативной интеграции с Notion. Обоим нужен Zapier или собственный скрипт. Разницу смотрите на странице сравнения с Bitly, а на странице тарифов - какие планы включают неограниченное число баз данных Notion.

Устранение неполадок: четыре проблемы, с которыми мы столкнулись в Beta

Во время Beta проявилось четыре класса проблем. Некоторые относятся к запланированной синхронизации, а не к текущему подключению, но полезно знать, на что обращать внимание.

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

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

Несоответствие типа свойства. Самая частая ошибка Beta. Пользователь выбрал для Destination колонку Notion типа «Text» вместо «URL». Теперь валидатор карты полей отмечает это при сохранении и отказывается продолжать. Если вы видите «Destination must be a URL property», сначала измените тип колонки в Notion.

Пользователь в нескольких рабочих пространствах с общими базами данных. Если один и тот же человек состоит в двух рабочих пространствах Notion и оба хотят подключить Elido, каждому рабочему пространству нужно собственное разрешение OAuth. Токен привязан к рабочему пространству, а не к пользователю. Процесс подключения обрабатывает это корректно; просто ожидайте, что нажать Connect придется дважды.

Если ваш случай не в этом списке, страница контактов ведет прямо к команде интеграций. Там мы видим проблемы быстрее, чем через обычную поддержку.

Что появится дальше

В roadmap стоят два следующих шага. Рецепт «форма Notion в короткую ссылку», чтобы отправка формы создавала отслеживаемую ссылку. И двусторонняя синхронизация по свойству Workspace, чтобы ссылка следовала за строкой при переносе между базами данных. Оба пункта по плану выйдут в третьем квартале; мы отметим их в журнале изменений.

Чтобы измерить эффект, в вводном материале по аналитике коротких ссылок рассказано, какие метрики действительно важны и как настроить строки дашборда в Notion, чтобы они отвечали на правильные вопросы.