Настройка интеграции Битрикс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 поддерживает webhooks — подписка на события доски через 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 flow при первом входе.

Создание задач из стикеров

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

Техническая реализация:

1. Miro webhook отправляет событие 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 — email берётся из профилей Б24.

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

• Miro: OAuth 2.0. Приложение регистрируется на https://miro.com/app/settings/user-profile/apps/. Scope: boards:read, boards:write, identity:read.
• Б24: OAuth 2.0 с scope task,sonet_group,user.
• Токены хранятся зашифрованными на middleware. Refresh выполняется автоматически.

Что внедряем

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