Налаштування інтеграції Бітрікс24 з Miro

Налаштування інтеграції Бітрікс24 з Miro

Команда проводить брейнштормінг та ретроспективи в Miro, але керує завданнями в Бітрікс24. Після кожної сесії хтось повинен вручну перенести стікери з дошки на завдання Б24. Зазвичай це робить найвідповідальніша людина — або ніхто не робить. Через два дні результати мозкового штурму втрачаються серед десятків дошок, а Б24 не отримує жодного нового завдання. Міст між візуальним плануванням та трекером завдань потрібно автоматизувати.

Архітектура інтеграції

Інтеграція використовує Miro REST API v2 та Б24 REST API. Miro надає API для роботи з дошками, стікерами, фреймами та коннекторами. Б24 надає вебгуки для подій завдань та CRM. Middleware обробляє обмін даними між системами.

Miro (webhook) → Middleware → Б24 REST API → Завдання/Коментарі
Б24 (подія) → Webhook → Middleware → Miro REST API → Стікери/Карточки

Miro підтримує вебгуки — підписку на события дошки через POST /v2/boards/{board_id}/webhooks. Middleware отримує сповіщення при створенні, зміні та видаленні елементів.

Вбудовування дошок Miro у Б24

Дошки Miro вбудовуються в інтерфейс Бітрікс24 двома способами:

• Iframe у завданні. До опису завдання або користувацького поля додається embed-посилання формату https://miro.com/app/live-embed/{board_id}/. Користувачі бачать інтерактивну дошку прямо в карточці завдання.
• Застосунок у маркетплейсі Б24. Локальний застосунок (тип — placement) вбудовує вджет Miro в карточку завдання або угоди через REST-розміщення TASK_VIEW_TAB. Користувачі відкривають вкладку «Дошка» і бачать прив'язану дошку Miro.

Для авторизації у вбудованій дошці Miro використовує власну сесію користувача. Middleware передає access_token через потік OAuth 2.0 при першому вході.

Створення завдань зі стікерів

Ключовий сценарій — перетворення стікерів Miro у завдання Б24. Middleware відстежує стікери з певним маркером (колір, тег або префікс у тексті):

Технічна реалізація:

1. Webhook Miro надсилає подію item_created або item_updated.
2. Middleware отримує дані стікера через GET /v2/boards/{board_id}/items/{item_id}.
3. Текст стікера розбирається: перший рядок — назва завдання, решта — опис.
4. Завдання створюється через tasks.task.add з прив'язкою до проекту (визначається за фреймом, який містить стікер).
5. ID створеного завдання записується назад на стікер як тег — для двосторонньої комунікації.

Синхронізація статусів

Коли стікер переміщується між фреймами на дошці (наприклад, з «To Do» на «In Progress»), middleware оновлює статус завдання в Б24. Фрейми відображаються на статуси:

• Middleware запитує позицію стікера через API і визначає, в якому фреймі він знаходиться.
• Назва фрейму порівнюється зі статусом завдання через конфігурацію.
• Викликається tasks.task.update з новим статусом.

Зворотний напрямок: коли статус завдання змінюється в Б24, middleware переміщує стікер у відповідний фрейм через PATCH /v2/boards/{board_id}/items/{item_id} з новими координатами.

Проектна співпраця

Для проектної роботи налаштуйте автоматичне створення дошки Miro при створенні проекту в Б24:

1. Подія ONSOCNETGROUPADD (створення проекту/групи) → middleware викликає POST /v2/boards із шаблоном дошки.
2. Посилання на дошку зберігається в описі проекту Б24.
3. Учасники проекту отримують доступ до дошки через POST /v2/boards/{board_id}/members — електронна пошта з профілів Б24.

Аутентифікація

• Miro: OAuth 2.0. Застосунок реєструється на https://miro.com/app/settings/user-profile/apps/. Область: boards:read, boards:write, identity:read.
• Б24: OAuth 2.0 з областю task,sonet_group,user.
• Маркери зберігаються зашифровані на middleware. Оновлення відбувається автоматично.

Що ми реалізуємо

• Middleware для двосторонньої інтеграції дошок Miro та завдань Б24
• Автоматичне створення завдань зі стікерів Miro з кольоровим маркуванням
• Вбудовування дошок Miro в інтерфейс Бітрікс24
• Синхронізацію статусів через відображення фреймів та стадій завдань
• Автоматичне створення дошок при запуску проектів
• Управління доступом учасників між системами