Налаштування інтеграції Бітрікс24 з Notion
Документація живе в Notion, а угоди та завдання — у Бітрікс24. Менеджер закриває угоду, потім вручну переходить до Notion, щоб оновити таблицю проектів. Розробник визначає вимоги в базі даних Notion, а потім дублює їх як завдання в Б24. Через місяць дві системи показують різні дані, і ніхто не знає, яка версія актуальна. Ручне копіювання між Б24 та Notion гарантує розсинхронізацію даних.
Архітектура інтеграції
Інтеграція працює через Notion API v1 та Б24 REST API. Notion надає API для роботи з базами даних, сторінками та блоками. Б24 надає вебгуки для підписки на событи CRM, завдань та бізнес-процесів. Middleware-сервер розташований між ними, слухає события обох сторін і перекладає дані.
Б24 (подія CRM/завдання) → Webhook → Middleware → Notion API → Database/Page
Notion (polling/webhook) → Middleware → Б24 REST API → CRM/завдання
Notion API поки не підтримує нативні вебгуки для відстеження змін. Middleware використовує polling — опитування бази даних Notion з фільтром last_edited_time кожні 30–60 секунд. Б24 використовує стандартні вебгуки через event.bind.
Синхронізація баз даних Notion з CRM
Основний сценарій — дзеркалювання записів CRM у базу даних Notion. Налаштуйте відображення полів:
| Поле CRM Б24 | Властивість бази даних Notion | Тип |
|---|---|---|
| TITLE (назва угоди) | Name (title) | title |
| STAGE_ID | Статус | select |
| OPPORTUNITY | Сума | number |
| ASSIGNED_BY_ID | Відповідальний | people / rich_text |
| COMPANY_ID → TITLE | Компанія | rich_text |
| DATE_CREATE | Дата створення | date |
| UF_* (користувацькі поля) | Користувацькі властивості | за типом |
Коли змінюється стадія угоди в Б24 (подія ONCRMDEALUPDATE), middleware оновлює відповідний запис у Notion через PATCH /v1/pages/{page_id} з новим значенням властивості select. У зворотному напрямку — коли статус змінюється в Notion, middleware викликає crm.deal.update.
Створення сторінок з подій CRM
Коли відбувається подія в Б24, middleware автоматично створює сторінку в Notion із заповненим змістом:
- Нова угода → сторінка в базі «Проекти» з реквізитами клієнта, сумою, відповідальною особою. Тіло сторінки містить шаблон: секції «Вимоги», «Строки», «Контакти».
- Виграна угода → сторінка в базі «Активні проекти» із автоматичним переносом даних з карточки угоди.
- Нове завдання → запис у базі Kanban-стилю Notion з прив'язкою до проекту.
Створення сторінки — це виклик POST /v1/pages із указанням parent.database_id та масиву properties. Вміст сторінки передається як масив блоків: paragraph, heading_2, to_do, table.
Двосторонні оновлення
Middleware ведення таблиця відображення: b24_entity_id ↔ notion_page_id. При кожному оновленні перевіряється джерело, щоб запобігти циклам:
- Б24 оновлює угоду → middleware записує
sync_source = "b24"у метадані. - Middleware оновлює сторінку Notion.
- При наступному polling middleware бачить змину, але перевіряє позначку часу — якщо оновлення сталося в межах 10 секунд після запису middleware, воно пропускається.
Для текстових полів використовується стратегія останнього запису вибагає перемогу — переважає останнє змінення. Для статусів — настроюваний пріоритет (ви можете вказати, яка система є основною).
Обмеження Notion API
Notion API має обмеження швидкості — 3 запити на секунду на інтеграцію. Middleware ставить запити в чергу та дотримується інтервалів. При отриманні 429 Too Many Requests — експоненціальна задержка.
Розмір корисного навантаження обмежений: максимум 100 блоків на один запит створення сторінки. Для більших документів middleware розділяє вміст на кілька викликів PATCH /v1/blocks/{block_id}/children.
Аутентифікація та доступи
- Notion: Internal Integration Token. Створюється в Settings → Integrations. Інтеграцію потрібно вручну підключити до кожної бази даних через «Add connections» — без цього API не видить базу.
-
Б24: OAuth 2.0 з областю
crm,task,user. Маркер оновлення оновлюється автоматично. - Middleware зберігає обидва токени зашифровані. Дані проходять тільки через ваш сервер.
Що ми реалізуємо
- Middleware для двосторонньої синхронізації Б24 CRM та баз даних Notion
- Автоматичне створення сторінок Notion із подій CRM
- Відображення полів CRM на властивості бази даних Notion
- Двосторонне оновлення статусів із захистом від циклів
- Чергу запитів з урахуванням обмежень швидкості Notion API
- Механізм polling для відстеження змін у Notion