Поля настройки интеграции

Каждая интеграция описывает поля, которые администратор заполняет при подключении: ключи доступа, адрес внешней системы, режим обмена, email, порт, интервал синхронизации и другие параметры.

Для интеграторов эти поля описываются в формате JSON Schema Draft-07. Благодаря этому SNABZHENETS+ строит форму настройки с подсказками, проверкой заполнения и маскировкой секретных полей.

Пример простых полей

{
  "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": true обрабатываются особым образом:

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

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

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

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

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

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

Хранение настроек

Заполненные настройки сохраняются в защищённом виде. Секретные поля не показываются пользователям и не возвращаются в открытом виде через API.

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

При обновлении настроек можно передать только изменившиеся поля. Если секретное поле не передано или передано пустым, прежнее значение сохраняется. Это позволяет изменить, например, интервал синхронизации или адрес сервиса, не вводя заново пароль или API-ключ.