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

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

Дизайнер оновлює макет у Figma, але розробник дізнається про це через два дні — коли менеджер випадково спитає в чаті. Посилання на макети розкидані по завданням, коментарям та приватним повідомленням. Актуальна версія — незрозуміло яка: до завдання прикріплено скриншот трьохтижневої давності, а поточний макет живе у гілці Figma, про яку знає лише автор. Без системи між Figma та Б24 дизайн-процес перетворюється на пошук актуальних посилань.

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

Інтеграція побудована на Figma REST API v1, Figma Webhooks v2 та Б24 REST API. Figma надає API для отримання даних про файли, коментарі та версії. Вебгуки надсилають сповіщення про зміни. Middleware з'єднує события Figma з сутностями Б24.

Figma (webhook) → Middleware → Б24 REST API → Завдання/Чат/Лента
Б24 (завдання/CRM) → Middleware → Figma API → Отримати дані файлу

Figma Webhooks підтримують события: FILE_UPDATE, FILE_VERSION_UPDATE, FILE_COMMENT, FILE_DELETE. Реєстрація — через POST /v2/webhooks з указанням team_id та event_type.

Прив'язка макетів до завдань

Кожне завдання Б24, пов'язане з дизайном, отримує посилання на файл Figma або конкретний фрейм. Два варіанти реалізації:

• Користувацьке поле. У завданнях Б24 створюється поле UF_FIGMA_URL. Middleware валідує формат посилання (https://www.figma.com/file/{file_key}/...) та витягує file_key та node_id для запитів API.
• Розміщення в карточці завдання. Локальний застосунок Б24 додає вкладку в карточку завдання (TASK_VIEW_TAB), яка відображає превью макету та основні метадані: назва файлу, останнє оновлення, кількість коментарів.

Превью макету отримується через GET /v1/images/{file_key} з параметром ids (список node_id). Figma повертає URL растрового зображення, яке middleware кешує та подає в інтерфейс Б24.

Сповіщення про оновлення дизайну

Коли файл змінюється в Figma, middleware надсилає сповіщення в Б24:

Подія FILE_VERSION_UPDATE — найважливіша. Приходить, коли дизайнер зберігає іменовану версію (Save to Version History). Middleware отримує webhook payload із file_key, file_name та timestamp, знаходить усі завдання Б24 з цим file_key у полі UF_FIGMA_URL та додає коментар: назва версії, час, посилання на файл.

Для FILE_COMMENT middleware витягає текст коментара через GET /v1/files/{file_key}/comments та перекладає його в чат відповідного проекту Б24 через im.message.add.

Workflow дизайн-ревю

Налаштуйте процес узгодження макетів через завдання Б24:

1. Дизайнер завершує макет і змінює статус завдання на «На ревю».
2. Middleware за подією ONTASKUPDATE запитує превью з Figma API і прикріплює поточний скриншот до завдання через task.commentitem.add.
3. Ревьюер бачить скриншот у завданні, залишає коментар.
4. Middleware, за необхідності, транслює коментар від Б24 назад до Figma через POST /v1/files/{file_key}/comments з координатами фрейму.

Це замикає цикл: дизайнер бачить фідбек у Figma, менеджер — у Б24. Ніхто не перемикається між інструментами.

Генерація превю

Middleware періодично (за розкладом або подією) оновлює превю макетів:

• Запит GET /v1/images/{file_key}?ids={node_ids}&format=png&scale=2 повертає URL зображень.
• Middleware завантажує зображення та загружує на диск Б24 через disk.file.uploadtofolder.
• Посилання на файл оновлюється в користувацькому полі завдання.

Обмеження швидкості Figma API — 120 запитів на хвилину. Middleware розподіляє запити з урахуванням обмеження.

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

• Figma: Personal Access Token або OAuth 2.0. Для команди рекомендується OAuth — маркер прив'язаний до користувача та має доступ до всіх файлів, до яких має доступ цей користувач.
• Б24: OAuth 2.0 з областю task,im,disk,user.
• Webhooks Figma прив'язані до team_id — одна підписка охоплює всі файли команди.

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

• Middleware для з'єднання файлів Figma з завданнями Б24
• Сповіщення про оновлення макетів та коментарів у завданнях та чатах Б24
• Автоматичну генерацію та оновлення превю макетів
• Workflow дизайн-ревю з двосторонньою синхронізацією коментарів
• Вбудовування превю Figma в карточку завдання Б24
• Кешування та ротацію превю з урахуванням обмежень швидкості