Продукт
API и интеграции: стабильные методы, личные токены и готовые связки
Для автоматизации есть два набора методов: небольшой стабильный Public API v1 (REST) и Backend API — всё, что умеет интерфейс. Доступ даёт личный токен, который никогда не шире прав своего владельца. Почта, Telegram, домен, единый вход (SSO) для ваших приложений и HTTP-шаги процессов подключаются в настройках, без доработки продукта.
Что получаете
Интеграции — без доработки продукта
API, токены и готовые связки входят в любую редакцию INFRAX, включая бесплатную Community Edition.
Стабильный Public API v1
Версионированный контракт, на который можно опираться надолго: заявки и комментарии, пользователи и группы, запросы портала, отчёты аналитики.
Backend API
Те же методы, которыми пользуется интерфейс, — для сценариев, которых нет в Public API. Меняются вместе с продуктом.
Swagger на вашем сервере
Описание OpenAPI обоих наборов открывается в продукте: методы, параметры и ответы видны сразу, их можно попробовать с токеном.
Токен не шире прав владельца
Робот получает выбранные приложения, наборы методов, источники прав и проекты на срок. Отозванные у владельца права сразу пропадают и у токена.
Почта, Telegram, домен
Письма становятся заявками, уведомления уходят на почту и в Telegram, пользователи и группы приходят из Active Directory, LDAP и FreeIPA.
Интеграции в процессах
HTTP-шаг вызывает внешнюю систему прямо из процесса на портале, шаги INFRAX создают заявки и запускают скрипты.
API
Два набора методов
Public API v1 — небольшой версионированный контракт: его методы и форматы меняются редко, на него стоит строить долгоживущие интеграции. Backend API — методы, которыми пользуется сам интерфейс: через них доступно всё, что умеет интерфейс, но они могут меняться вместе с версией продукта. Оба набора описаны в OpenAPI, Swagger открывается на вашем сервере.
| Раздел продукта | Что есть в Public API v1 |
|---|---|
| Сервис-деск и инфраструктура | Проекты, услуги, узлы, метки, участники заявок; заявки — список, создание, чтение, изменение; комментарии к заявкам |
| Вход и права | Пользователи — список, создание, изменение, удаление, сброс пароля; итоговые права пользователя; группы и проекты; журнал аудита |
| Портал сотрудника | Проекты, услуги каталога, процессы; запросы — список, создание из услуги каталога, чтение, сообщения |
| Аналитика | Опубликованные дашборды; выгрузка дашборда в PDF |
Запросы с личным токеном
Один и тот же токен передаётся в заголовке Authorization: Bearer и в Public API, и в Backend API — если при выпуске выбраны оба набора.
# список проектов
curl -H "Authorization: Bearer <токен>" \
"https://<адрес-infrax>/api/public/v1/projects?limit=1"
# новая заявка в сервис-деске
curl -X POST -H "Authorization: Bearer <токен>" -H "Content-Type: application/json" \
-d '{"project_id": "<проект>", "service_id": "<услуга>", "title": "Не проводится выписка", "text": "…"}' \
"https://<адрес-infrax>/api/public/v1/tickets"application/problem+json, длинные списки отдаются страницами. Существующие интеграции по учётным данным приложения OpenID Connect (OIDC) продолжают работать рядом с токенами. Доступ
Личные токены приложений
Робот получает часть доступа своего владельца, а не логин и пароль. Токен выпускается мастером в разделе входа и прав: «Мои» → «Секреты» → «Токены приложений». Выпускать токены может пользователь с правом «Выпуск токенов приложений» — только от своего имени.
Выпуск мастером: что именно делегируется
На первом шаге выбираются приложения и наборы методов — Public API v1, Backend API или оба. На втором — из каких источников токен берёт права: личные права владельца, его группы, общая группа «Все», и в каких проектах он работает. На третьем мастер считает итоговые разрешения, задаёт название и срок действия и только после проверки выпускает токен.
- У каждой группы видно, сколько разрешений она даёт
- Границы фиксируются при выпуске: новые права владельца токен не расширяют
- Полный секрет показывается один раз, рядом — готовый пример cURL
Управление: продлить, сменить секрет, отозвать
В списке токенов видны название и безопасный префикс, состояние, приложения, срок и последняя активность. Токен продлевается на 30 дней без смены секрета, секрет можно сменить — старый сразу перестаёт работать, — а отзыв необратим. Токен перестаёт работать и сам: по сроку, при удалении или отключении владельца, а временная блокировка владельца его приостанавливает.
- Отозванные у владельца права сразу сужают токен
- В режиме «Смотреть как» выпуск и управление токенами недоступны
- Существующие интеграции OIDC-приложений работают как прежде
Интеграции
Готовые связки
Связи с почтой, мессенджером, доменом и внешними системами настраиваются в самом продукте. Ниже — как это выглядит на экранах демонстрационного стенда «Северный склад».
HTTP-шаг процесса на портале
Процесс на портале обращается к внешней системе сам: шаг HTTP отправляет запрос с методом, заголовками и телом JSON, куда подставляются данные из заявки. Ответ сохраняется в переменную процесса, и по нему решается, куда процесс пойдёт дальше. Для защищённых API шаг сам получает токен по OAuth 2.0 Client Credentials.
- GET, POST, PUT, PATCH и DELETE
- Таймаут, проверка SSL-сертификата, поведение при ошибке
- Рядом — шаги «Скрипт Infrax» и «Тикет Infrax»
Письма становятся заявками
Почта подключается в разделе входа и прав: входящие письма становятся заявками, а ответы исполнителя уходят заявителю письмом в ту же переписку. Проект заявки выбирается по адресу отправителя — правилами в настройках службы поддержки, где самое точное совпадение выигрывает. Рассылки и автоответы не получают автоподтверждения, а уведомления о недоставке не превращаются в новые заявки.
- Ответ на письмо попадает в ту же заявку по её номеру и заголовкам письма
- Вложения и картинки из письма сохраняются в заявке
- Правило «*» — проект для всех остальных писем
Уведомления на почту и в Telegram
Уведомления о событиях — новая заявка, инцидент, проблема, назначение, смена статуса, просрочка — приходят на почту, в Telegram и во встроенный центр уведомлений. Каждый сотрудник сам выбирает в своих предпочтениях, о каких событиях его оповещать, а каналы доставки подключает в разделе входа и прав.
- Подписки отдельно для поддержки, исполнителя и наблюдателя
- Telegram — канал уведомлений, заявки из него не создаются
Внешние базы данных для отчётов
Аналитика подключается к базам других систем: MySQL, ClickHouse, Trino, BigQuery, DuckDB, YDB и другим из списка поддерживаемых. Диаграммы по внешним данным встают на те же дашборды, что и данные продукта. Подробнее — на странице «Аналитика и отчётность».
- Базы самого продукта подключены сразу
- Отчёт выгружается в PDF и через Public API
Домен и каталоги
Active Directory, LDAP и FreeIPA: синхронизация пользователей и групп, вход по доменной учётной записи, в том числе через контроллер домена в филиале. Подробнее — «Вход и права».
Единый вход (SSO) для ваших приложений
Ваши приложения входят через OIDC, а веб-приложение без поддержки OIDC закрывается прокси раздела входа и прав без доработки самого приложения.
Шаги INFRAX в процессах
«Тикет Infrax» создаёт заявку, пишет в неё, меняет поля и метки; «Скрипт Infrax» запускает скрипт на узлах. Подробнее — «Портал и процессы».
В том же продукте
С этими задачами работает API
Методы и связки принадлежат задачам продукта: один токен и одни права на все разделы.
Сервис-деск ITSM
Заявки и комментарии создаются и читаются методами Public API, письма становятся заявками, а процессы портала заводят их шагом «Тикет Infrax».
Страница задачиДоступ и безопасностьВход и права IAM · SSO
Пользователи, группы, итоговые права и журнал аудита — в Public API; там же выпускаются личные токены, а домен подключается синхронизацией.
Страница задачиПоддержка пользователейПортал и процессы ESM · BPM
Запрос из каталога услуг создаётся через API, а процесс сам вызывает внешние системы HTTP-шагом.
Страница задачиКонтрольАналитика и отчётность BI
Опубликованные дашборды и их выгрузка в PDF доступны в Public API, внешние базы подключаются к отчётам.
Страница задачиИнфраструктураАвтоматизация и бэкап
Задание планировщика в режиме «Вручную / через API» запускается командой извне, а скрипт может стать шагом процесса.
Страница задачиИнфраструктураМониторинг
Список узлов и карточка узла есть в Public API: внешняя система получает те же узлы, что видят инженеры, в пределах прав токена.
Страница задачиТехнические сведения
Для версии 2.0
- Public API v1
- Базовый путь /api/public/v1 в каждом разделе; Swagger — /api/public/v1/docs
- Backend API
- Методы интерфейса; Swagger — /api/backend/docs
- Описание
- OpenAPI: JSON-описание рядом со Swagger
- Аутентификация
- Authorization: Bearer <личный токен>; для серверных интеграций — учётные данные OIDC-приложения
- Токены
- Приложения и наборы методов, источники прав, проекты, срок; продление, смена секрета, отзыв
- Ответы Public API
- Коды HTTP, ошибки в application/problem+json, списки страницами
- Почта
- SMTP и IMAP через раздел входа и прав; письма в заявки, ответы в переписку
- Уведомления
- Почта, Telegram, встроенный центр уведомлений
- Процессы
- HTTP-шаг с OAuth 2.0 Client Credentials, шаги «Скрипт Infrax» и «Тикет Infrax», отправка письма или сообщения в Telegram
Вопросы
Частые вопросы
Чем Public API отличается от Backend API?
Public API v1 — небольшой версионированный контракт: методы и форматы меняются редко, на нём стоит строить долгоживущие интеграции. Backend API — методы интерфейса: через них доступно всё, что умеет интерфейс, но они могут меняться с новой версией продукта.
Можно ли перенести заявки из другой системы?
Готового переноса заявок из других систем нет. Заявки и комментарии создаются методами Public API, пользователи — методами раздела входа и прав или синхронизацией с доменом, а статьи базы знаний импортируются из файлов CSV.
Какие есть каналы уведомлений?
Почта, Telegram и встроенный центр уведомлений в интерфейсе. SMS и других мессенджеров нет; Telegram работает только на уведомления, заявки из него не создаются.
Что будет с токеном, если сотрудник уволится?
Токен перестаёт работать, как только владельца удаляют или отключают; временная блокировка владельца приостанавливает и его токены. Права, отобранные у владельца, сразу пропадают и у токена.
Кейс, где процесс портала сам выполняет шаги в других разделах продукта:
