Справочник интеграций

Назначение

Справочник интеграций позволяет настроить обращение ERP к внешним REST-сервисам без программирования: задать адрес API, авторизацию, методы, параметры, тело и ожидаемые ответы, а также правила выполнения запросов. Настроенные методы можно вызывать из бизнес-процессов и динамического кода.

Расположение: меню Интеграции.

Главный экран

На главном экране показаны настроенные интеграции.

Здесь можно:

найти интеграцию по наименованию;
добавить интеграцию;
включить или выключить её тумблером;
открыть редактор;
выгрузить настройки в JSON-файл;
удалить интеграцию после подтверждения.

Выключенная интеграция остаётся в справочнике, но её методы недоступны для выполнения.

Импорт и экспорт

Кнопка Импорт загружает интеграцию из JSON-файла. При импорте создаётся новая запись со всеми описанными в файле методами, параметрами, телами, ответами и расширенными настройками.

Кнопка экспорта находится в строке интеграции. По умолчанию авторизационные данные в файл не попадают: после импорта их нужно заполнить заново. Включайте флаг Выгружать данные авторизации только для передачи файла по защищённому каналу.

Настройка интеграции

Редактор состоит из пяти вкладок: Основные, Авторизация, Расширенные, Методы и История. Для новой интеграции сначала сохраните вкладку Основные: остальные вкладки станут доступны после создания записи.

Основные

Наименование — название интеграции в справочнике.
Описание — назначение интеграции.
Базовый URL — общий адрес сервиса. Путь конкретного метода добавляется к этому адресу.

Авторизация

Доступны три типа авторизации:

Отсутствует — запрос отправляется без авторизационных данных;
BASIC — имя пользователя, пароль и заголовок для HTTP Basic;
API_KEY — ключ API и параметры его передачи.

Набор полей меняется при выборе типа. Авторизационные данные не восстанавливаются из истории версий и по умолчанию не выгружаются при экспорте.

Расширенные

Вкладка содержит семь независимых блоков. Тумблер на карточке включает или выключает уже сохранённую настройку; нажатие на карточку открывает её редактор.

Timeout

Задаёт таймаут чтения и таймаут записи в миллисекундах.

HTTP

Ограничивает набор HTTP-протоколов, которые разрешено использовать клиенту. Можно выбрать HTTP/1.0, HTTP/1.1, HTTP/2 и HTTP/3.

Worker

Ограничивает максимальное количество одновременных запросов для интеграции и максимальное количество запросов на один хост.

SSL

Параметры Игнор SSL и Проверка hostname управляют проверкой сертификата и имени узла.

Отключение проверки сертификата или имени узла снижает защищённость соединения. Используйте такие настройки только для доверенных сервисов и после согласования требований к безопасности.

Circuit breaker

Circuit breaker временно прекращает вызовы нестабильного сервиса и пробует восстановить работу после заданного интервала. В блоке задаются:

порог ошибок и время ожидания в состоянии Open;
порог и длительность медленного запроса;
число пробных запросов в Half-Open;
размер скользящего окна и минимальное число запросов для расчёта.

Rate limiter

Ограничивает частоту обращений: задаёт время ожидания разрешения, период обновления лимита и количество запросов за период.

Logging

Задаёт уровень логирования HTTP-обмена и отдельно разрешает запись тела запроса и ответа.

Тела запросов и ответов могут содержать персональные или авторизационные данные. Не включайте их логирование без необходимости.

Методы

На вкладке показаны эндпоинты интеграции. Метод можно добавить, включить или выключить, отредактировать и удалить.

Редактор метода состоит из вкладок Основные, Параметры, Тело, Ответы и Тестирование.

Основные настройки метода

Задайте наименование, описание, HTTP-метод и путь. В нижней части формы показан итоговый URL, составленный из базового URL интеграции и пути метода.

Параметры

Параметр можно передать в строке запроса (Query), в пути (Path) или в заголовке (Header). Для параметра задаются наименование, описание, тип (string, number или boolean), значение по умолчанию и признак обязательности.

Тело

Для тела запроса указываются Content-Type, признак обязательности и схема данных. У метода может быть несколько вариантов тела с разными Content-Type.

Схему можно собрать визуально или отредактировать как JSON:

в режиме Конструктор поля образуют дерево; для каждого поля задаются тип, описание, значение по умолчанию, допустимость null и обязательность;
в режиме JSON редактируется та же схема в текстовом виде;
блок Preview показывает итоговую структуру как Schema или JSON;
действие Загрузить из модели копирует схему из справочника моделей. После загрузки эта копия редактируется независимо от исходной модели.

Ответы

Для каждого ожидаемого ответа задаются HTTP-код, Content-Type, описание и схема данных. Схема ответа настраивается тем же конструктором, что и тело запроса, и также может быть загружена из модели.

Тестирование

Вкладка собирает итоговый URL и запрос из сохранённых настроек. Перед запуском проверьте параметры и тело; результат вызова появится в области Response. Действие Copy as curl копирует эквивалентную команду для запуска вне ERP.

История

История фиксирует изменения интеграции, методов, параметров, тел, ответов, авторизации, расширений и операций импорта/экспорта. Записи можно отфильтровать по разделу.

Записи с сохранённым состоянием отмечены номером версии. Перед восстановлением система показывает список изменений. Текущее состояние сохраняется отдельной версией, поэтому восстановление можно отменить повторным откатом.

При восстановлении версии авторизационные данные не меняются. Если прежний идентификатор метода уже занят, метод создаётся с новым идентификатором; его нужно повторно выбрать в блоках BPMN, которые вызывали этот метод.

Справочник моделей

Справочник моделей хранит переиспользуемые схемы данных. Модель создаётся тем же визуальным конструктором и затем может быть загружена в тело запроса или ответ метода.

Расположение: меню Справочник моделей.