# Интеграция Baserow и Figma - синхронизация дизайн-данных

> Дизайн-токены из таблиц Baserow передаются в переменные Figma через REST API, а события Figma попадают обратно в таблицу через вебхук.

Source: https://opennix.org/docs/baserow/integrations/figma-integration/


Готовой кнопки для прямой синхронизации между Baserow и Figma нет, но в открытой редакции связку можно собрать самостоятельно: скрипт-мост читает строки таблицы Baserow и через REST API обновляет переменные (Variables) Figma, а в обратную сторону вебхуки Figma отправляют события - комментарии, публикацию библиотек, смену статуса - в автоматизацию Baserow, которая создаёт по ним строки; оба сценария не требуют плагина и работают даже без открытого файла у дизайнера.

## Как это работает

Дизайн и данные обычно живут в разных инструментах: дизайнеры работают в Figma, а продуктовые данные, копирайтинг и статусы задач - в Baserow. Классический мостик между ними - плагин, но плагин зависит от того, откроет ли его дизайнер и нажмёт ли «Sync» вручную. Прямое обращение к REST API Figma работает иначе - оно не зависит от того, открыт ли файл, и выполняется по расписанию или по событию.

Есть два независимых архитектурных паттерна:

1. **Синхронизация переменных (Baserow → Figma):** значения дизайн-токенов (цвета, текст, числа) хранятся в Baserow и по расписанию отправляются в Figma Variables через REST API.
2. **Журнал активности (Figma → Baserow):** вебхуки Figma логируют комментарии и обновления файлов прямо в таблицу Baserow для общего обзора проекта.

Такой подход надёжнее плагина: скрипт обращается к серверу Figma напрямую и работает, даже если файл никто не открывал.

## Вариант 1. Синхронизация переменных (Baserow → Figma)

Вместо того чтобы дизайнер вручную вбивал hex-коды цветов или тексты, слои в Figma привязываются к переменным (Variables), а Baserow выступает базой данных для их значений. Когда маркетинг меняет цену или заголовок в Baserow, скрипт передаёт это обновление напрямую в Figma.

### Варианты использования

- **Локализация:** тексты для разных языков хранятся в столбцах Baserow.
- **Темизация:** цветовые токены для светлой и тёмной темы.
- **Данные продукта:** актуальные цены или остатки, которые отображаются в макетах.

### Шаг 1. Предварительные требования

- **Персональный токен доступа Figma.** В файловом браузере Figma откройте меню аккаунта в левом верхнем углу, перейдите в **Settings → Security** и в разделе **Personal access tokens** нажмите **Generate new token**.
- **database-токен (API-токен) Baserow.** Подробнее о создании и правах такого токена - в статье [«Database-токены (API-токены) Baserow»](/docs/baserow/webhook-api/personal-api-tokens/). Не передавайте токены никому, кому не готовы дать доступ к своим данным.
- **Ключ файла Figma (File Key).** Буквенно-числовое значение из URL дизайн-файла - оно стоит между типом файла и его именем, например `figma.com/{file_type}/{file_key}/{file_name}`.

Токен Figma передаётся в заголовке `X-Figma-Token` при каждом запросе к API.

### Шаг 2. Скрипт-мост

API Figma пассивен - он не отправляет данные сам, поэтому нужен внешний планировщик (GitHub Action или обычный cron-скрипт), который выполняет два шага:

1. `GET`-запрос к Baserow - например, к таблице «Brand Assets» - через [REST API Baserow](/docs/baserow/webhook-api/database-api/).
2. `POST`-запрос с обновлениями в эндпоинт Figma `/v1/files/:file_key/variables`, который позволяет массово создавать, обновлять и удалять переменные и их коллекции.

```python
import requests

# Configuration
BASEROW_API_URL = "https://api.baserow.io/api/database/rows/table/YOUR_TABLE_ID/"
FIGMA_API_URL = "https://api.figma.com/v1/files/YOUR_FILE_KEY/variables"
HEADERS_BASEROW = {"Authorization": "Token YOUR_BASEROW_TOKEN"}
HEADERS_FIGMA = {"X-Figma-Token": "YOUR_FIGMA_TOKEN", "Content-Type": "application/json"}

def sync_design_tokens():
    # 1. Fetch "Single Source of Truth" from Baserow
    response = requests.get(BASEROW_API_URL, headers=HEADERS_BASEROW, params={"user_field_names": "true"})
    data = response.json()

    # Initialize the list to hold all our value updates
    value_updates = []

    # 2. Iterate through rows and prepare Figma updates
    for row in data['results']:
        variable_id = row['Figma Variable ID'] # e.g., "VariableID:123"
        mode_id = row['Figma Mode ID']         # e.g., "1:0" (Required by Figma)
        new_value = row['Value']               # e.g., "Welcome Home"

        # 3. Append to our update list using Figma's required schema
        value_updates.append({
            "variableId": variable_id,
            "modeId": mode_id,
            "value": new_value
        })

    # 4. Construct the final payload and push to Figma
    payload = {
        "variableModeValues": value_updates
    }

    # 5. Make the atomic POST request
    response = requests.post(FIGMA_API_URL, headers=HEADERS_FIGMA, json=payload)

    if response.status_code == 200:
        print(f"Successfully updated {len(value_updates)} variable values!")
    else:
        print(f"Failed to update variables. Error: {response.status_code}")
        print(response.json())

sync_design_tokens()
```

Figma ожидает конкретные типы данных - строки, числа или объекты RGBA. Скрипт играет роль переводчика между тем, как значение хранится в Baserow, и тем форматом, которого ожидает Figma.

## Вариант 2. Журнал активности (Figma → Baserow)

Если нужно отслеживать не контент, а сам процесс работы над дизайном, используются вебхуки Figma: они позволяют наблюдать за событиями в файле - например, когда участник оставляет комментарий или в истории файла появляется новая версия - и превращают Baserow в живую ленту активности дизайн-команды.

Создание вебхука - операция уровня Tier 2, поэтому персональный токен доступа Figma должен быть выпущен с областью доступа `webhooks:write`.

### Варианты использования

- **Design QA:** новый комментарий к файлу автоматически создаёт задачу в Baserow.
- **Контроль версий:** публикация обновления библиотеки записывает историю версий в Baserow.

### Типы событий Figma

| Тип события | Где применяется | Ключевые данные для Baserow |
|---|---|---|
| `FILE_COMMENT` | Design QA: фиксация обратной связи дизайнеров и превращение её в задачи | текст комментария, упоминания (@mentions), время |
| `DEV_MODE_STATUS_UPDATE` | Отслеживание передачи в разработку: момент готовности фрейма | ID узла, статус (`READY_FOR_DEV`), сообщение об изменении |
| `LIBRARY_PUBLISH` | Контроль версий: обновление компонента дизайн-системы | список созданных и изменённых компонентов и переменных |

### Шаг 1. Настройка автоматизации в Baserow

1. Создайте таблицу **«Design Log»** в Baserow.
2. Создайте автоматизацию с триггером **«Receive an HTTP request (webhook)»**.
3. Скопируйте URL вебхука.

Подробнее о механике самого триггера и приёма запросов - в статье [«Вебхуки в Baserow»](/docs/baserow/webhook-api/webhooks/).

### Шаг 2. Создание вебхука в Figma

Слушатель регистрируется POST-запросом - из терминала или через инструмент вроде Postman. По умолчанию Figma сразу отправляет на указанный эндпоинт тестовое событие `PING`, подтверждая, что вебхук работает и будет получать обновления.

```bash
curl -X POST https://api.figma.com/v2/webhooks \
-H "X-Figma-Token: YOUR_PERSONAL_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "event_type": "FILE_COMMENT",
  "context": "file",
  "context_id": "YOUR_FILE_KEY",
  "endpoint": "YOUR_BASEROW_WEBHOOK_URL",
  "passcode": "my_secure_secret",
  "status": "ACTIVE",
  "description": "Sync Figma comments to Baserow Task Log"
}'
```

Чтобы отслеживать все файлы проекта или команды, замените `context` на `project` или `team` и укажите соответствующий идентификатор вместо ключа файла.

Обязательно задайте `passcode`: Figma добавит эту строку в каждый отправляемый запрос, и по ней в автоматизации Baserow можно проверить, что данные действительно пришли от Figma, а не из постороннего источника.

### Шаг 3. Сопоставление полезной нагрузки с данными Baserow

Когда дизайнер оставляет комментарий, Figma отправляет объёмный JSON. В действии «Create Row» нужно сопоставить конкретные поля:

- `triggered_by.handle` → поле «Исполнитель».
- `comment[0].text` → поле «Описание задачи».
- `https://www.figma.com/file/YOUR_FILE_KEY?node-id=...` → поле «Ссылка».

### Устранение типичных проблем

- **401 Unauthorized:** у database-токена должно быть право записи (Write), если данные отправляет сторона Figma; перед значением токена в заголовке обязательно должно стоять слово `Token`.
- **Правило 30 минут:** событие `FILE_UPDATE` срабатывает только после 30 минут бездействия в файле - для мгновенной фиксации изменений используйте `FILE_COMMENT`.
- **Проверка доставки:** эндпоинт `GET /v2/webhooks/:webhook_id/requests` показывает журнал всех попыток Figma обратиться к вашему вебхуку.
- **Формат цвета:** переменные Figma ожидают цвет в виде десятичного объекта RGBA (например, `{"r": 1, "g": 0.5, "b": 0, "a": 1}`), а не HEX-кода - проверьте, что значения в Baserow приведены к этому формату.

## Часто задаваемые вопросы

**Обязательно ли настраивать оба сценария сразу?** Нет - синхронизация переменных и журнал активности не зависят друг от друга. Можно включить только передачу дизайн-токенов, только логирование событий Figma или оба варианта вместе, в зависимости от задачи команды.

**Нужен ли плагин Figma для этой интеграции?** Нет - оба сценария работают напрямую через REST API и вебхуки Figma, без установки плагина и без необходимости вручную открывать файл и запускать синхронизацию.

**Как получить мгновенную реакцию на изменение файла, а не раз в 30 минут?** Используйте событие `FILE_COMMENT` вместо `FILE_UPDATE` - оно срабатывает сразу после действия дизайнера, а не после периода бездействия в файле.

Смежные темы - обзор [REST API Baserow](/docs/baserow/webhook-api/database-api/) для прямых запросов к таблицам без вебхуков и [интеграция с Tally](/docs/baserow/integrations/tally-integration/) как ещё один пример приёма внешних данных через вебхук-триггер автоматизации.