Схема конфигурации

Каждая интеграция описывает свои поля настройки через configSchema — JSON Schema Draft-07. Это позволяет платформе автоматически строить форму настройки с валидацией, подсказками и корректной маскировкой секретных полей.

Формат схемы

{
  "type": "object",
  "required": ["botToken", "chatId"],
  "properties": {
    "botToken": {
      "type": "string",
      "title": "Bot Token",
      "description": "Токен бота из @BotFather",
      "x-secret": true
    },
    "chatId": {
      "type": "string",
      "title": "Chat ID",
      "description": "ID чата или канала (например: -1001234567890)"
    }
  }
}

Расширение x-secret

Поля с флагом "x-secret": true обрабатываются особым образом:

• При отображении — значение маскируется: ••••••••
• При обновлении — если поле не передано или передано null, существующее значение сохраняется
• В API-ответах — секретное значение никогда не возвращается

Используйте x-secret: true для токенов, паролей, API-ключей и любых чувствительных данных.

Поддерживаемые типы полей

JSON Schema тип	Описание	Пример
string	Строка	API-ключ, URL, email
string + format: uri	Адрес URL	Webhook URL
string + format: email	Email-адрес	Адрес получателя
number	Число	Таймаут, лимит
integer	Целое число	Порт, количество
boolean	Флаг	Включить/выключить опцию
string + enum	Выбор из списка	Окружение: production / sandbox

Пример расширенной схемы

{
  "type": "object",
  "required": ["apiKey", "baseUrl", "environment"],
  "properties": {
    "apiKey": {
      "type": "string",
      "title": "API Key",
      "description": "Секретный ключ из личного кабинета",
      "x-secret": true,
      "minLength": 32
    },
    "baseUrl": {
      "type": "string",
      "format": "uri",
      "title": "Base URL",
      "description": "URL вашего экземпляра системы"
    },
    "environment": {
      "type": "string",
      "title": "Окружение",
      "enum": ["production", "sandbox"],
      "default": "production"
    },
    "syncIntervalMinutes": {
      "type": "integer",
      "title": "Интервал синхронизации (минуты)",
      "minimum": 5,
      "maximum": 1440,
      "default": 60
    },
    "notifyOnError": {
      "type": "boolean",
      "title": "Уведомлять об ошибках",
      "default": true
    }
  }
}

Хранение конфигурации

Заполненная конфигурация шифруется алгоритмом AES-256-GCM перед сохранением в базе данных. Ключ шифрования уникален для каждой установки (производный контекст включает tenantId и installationId).

Конфигурация расшифровывается только в момент выполнения операций интеграции на сервере — она никогда не передаётся клиенту в открытом виде.

Частичное обновление

При обновлении конфига через PATCH /api/v1/integrations/installations/:id/config платформа выполняет merge:

1. Расшифровывает текущий конфиг
2. Накладывает новые значения поверх
3. Для x-secret полей с null значением — оставляет старое
4. Шифрует и сохраняет результат

Это позволяет обновлять только часть полей, не зная значений секретных полей.