SvayaИИ-платформаПлатформаПримерыПродуктыВнедрение

Svaya / Документация / Программный интерфейс

Внешние системы

Здесь собраны адреса, параметры, поля запросов и коды ответов раздела «Внешние системы». Каждая операция описана отдельно, с таблицами полей.

Описание собрано из договора core-api, версия 1.12.0. Как получить токен и в каком формате приходят ошибки, написано на странице «Обзор и вход».

Перечень внешних систем. Секрета в ответе нет.

GET /api/core/v1/external-systems операция listExternalSystems

Канал staff; действие PDP `read` на `core:access:external-system` (администратор платформы, аудитор).

Ответы

200. Перечень

Поля ответа

ПолеТипОбязательноОписание
itemsobject[]да
items[].idstring (uuid)да
items[].clientIdstringда
items[].titlestringда
items[].descriptionstringда
items[].packagesstring[]да
items[].assistantsstring (uuid)[]да
items[].capabilitiesstring[]да
items[].enabledbooleanда
items[].createdBystringда
items[].createdAtstring (date-time)да
items[].updatedBystringда
items[].updatedAtstring (date-time)да
items[].sectionsobject[]нет
items[].sections[].sectionIdstring (uuid)да
items[].sections[].namestring | nullда

403. Ошибка RFC 9457

Завести внешнюю систему. Секрет — в ответе один раз.

POST /api/core/v1/external-systems операция createExternalSystem

Канал staff; действие PDP `create`. Клиент заводится в системе входа выключенным и включается последним, после записи строки. Секрет (32 случайных байта, base64url) нигде не пишется. Ошибки: 400 `validation-failed`; 403 `forbidden`; 422 `package-unknown` «Автоматизации «{id}» на платформе нет»; 503 `identity-unavailable` «Система входа не ответила — изменение не выполнено. Повторите позже.»

Параметры

ПолеТипОбязательноОписание
X-BM-CSRF (заголовок)stringдаЗаголовок CSRF шлюза на изменяющих вызовах канала staff.

Поля тела запроса

ПолеТипОбязательноОписание
titlestringда
descriptionstringнет
packagesstring[]даАвтоматизации установки, которые система вправе запускать.
assistantsstring (uuid)[]нетПомощники, которых система вправе запускать (блок C).
capabilitiesstring[]нет`metrics` — чтение метрик установки (`getMonitoringFederate`).

Ответы

201. Система заведена

Поля ответа

ПолеТипОбязательноОписание
systemobjectдаВнешняя система. Секрета здесь нет никогда.
system.idstring (uuid)да
system.clientIdstringда
system.titlestringда
system.descriptionstringда
system.packagesstring[]да
system.assistantsstring (uuid)[]да
system.capabilitiesstring[]да
system.enabledbooleanда
system.createdBystringда
system.createdAtstring (date-time)да
system.updatedBystringда
system.updatedAtstring (date-time)да
system.sectionsobject[]нет
system.sections[].sectionIdstring (uuid)да
system.sections[].namestring | nullда
secretstringдаПоказывается один раз.
tokenUrlstringдаВнешний адрес выдачи токена системы входа (`perimeter.public_url` и путь realm; тот же, что у входа сотрудников).

400. Ошибка RFC 9457

403. Ошибка RFC 9457

422. Ошибка RFC 9457

503. Ошибка RFC 9457

Изменить внешнюю систему (название, описание, разрешённые автоматизации, помощников, возможности)

PUT /api/core/v1/external-systems/{id} операция updateExternalSystem

Канал staff; действие PDP `update`. Ошибки: 400, 403, 404 `not-found`, 422 `package-unknown`.

Параметры

ПолеТипОбязательноОписание
id (в адресе)string (uuid)да
X-BM-CSRF (заголовок)stringдаЗаголовок CSRF шлюза на изменяющих вызовах канала staff.

Поля тела запроса

ПолеТипОбязательноОписание
titlestringда
descriptionstringнет
packagesstring[]даАвтоматизации установки, которые система вправе запускать.
assistantsstring (uuid)[]нетПомощники, которых система вправе запускать (блок C).
capabilitiesstring[]нет`metrics` — чтение метрик установки (`getMonitoringFederate`).

Ответы

200. Система изменена

Поля ответа

ПолеТипОбязательноОписание
idstring (uuid)да
clientIdstringда
titlestringда
descriptionstringда
packagesstring[]да
assistantsstring (uuid)[]да
capabilitiesstring[]да
enabledbooleanда
createdBystringда
createdAtstring (date-time)да
updatedBystringда
updatedAtstring (date-time)да
sectionsobject[]нет
sections[].sectionIdstring (uuid)да
sections[].namestring | nullда

400. Ошибка RFC 9457

403. Ошибка RFC 9457

404. Ошибка RFC 9457

422. Ошибка RFC 9457

Отключить внешнюю систему. Уже выданный токен перестаёт проходить права не позже чем через 30 с.

POST /api/core/v1/external-systems/{id}:disable операция disableExternalSystem

Канал staff; действие PDP `update`. Клиент выключается в системе входа ДО записи строки; система входа не ответила — 503 `identity-unavailable`, ничего не изменено.

Параметры

ПолеТипОбязательноОписание
id (в адресе)string (uuid)да
X-BM-CSRF (заголовок)stringдаЗаголовок CSRF шлюза на изменяющих вызовах канала staff.

Ответы

200. Система отключена

Поля ответа

ПолеТипОбязательноОписание
idstring (uuid)да
clientIdstringда
titlestringда
descriptionstringда
packagesstring[]да
assistantsstring (uuid)[]да
capabilitiesstring[]да
enabledbooleanда
createdBystringда
createdAtstring (date-time)да
updatedBystringда
updatedAtstring (date-time)да
sectionsobject[]нет
sections[].sectionIdstring (uuid)да
sections[].namestring | nullда

403. Ошибка RFC 9457

404. Ошибка RFC 9457

503. Ошибка RFC 9457

Включить внешнюю систему

POST /api/core/v1/external-systems/{id}:enable операция enableExternalSystem

Канал staff; действие PDP `update`. Клиент включается в системе входа, затем строка получает `enabled = true`.

Параметры

ПолеТипОбязательноОписание
id (в адресе)string (uuid)да
X-BM-CSRF (заголовок)stringдаЗаголовок CSRF шлюза на изменяющих вызовах канала staff.

Ответы

200. Система включена

Поля ответа

ПолеТипОбязательноОписание
idstring (uuid)да
clientIdstringда
titlestringда
descriptionstringда
packagesstring[]да
assistantsstring (uuid)[]да
capabilitiesstring[]да
enabledbooleanда
createdBystringда
createdAtstring (date-time)да
updatedBystringда
updatedAtstring (date-time)да
sectionsobject[]нет
sections[].sectionIdstring (uuid)да
sections[].namestring | nullда

403. Ошибка RFC 9457

404. Ошибка RFC 9457

503. Ошибка RFC 9457

Заменить секрет внешней системы. Новый секрет — в ответе один раз.

POST /api/core/v1/external-systems/{id}:rotate-secret операция rotateExternalSystemSecret

Канал staff; действие PDP `update`. Прежний секрет перестаёт действовать сразу после ответа системы входа.

Параметры

ПолеТипОбязательноОписание
id (в адресе)string (uuid)да
X-BM-CSRF (заголовок)stringдаЗаголовок CSRF шлюза на изменяющих вызовах канала staff.

Ответы

200. Секрет заменён

Поля ответа

ПолеТипОбязательноОписание
secretstringда
tokenUrlstringда

403. Ошибка RFC 9457

404. Ошибка RFC 9457

503. Ошибка RFC 9457

listExternalSystemSections

GET /api/core/v1/external-systems/{id}/sections операция listExternalSystemSections

Канал staff; действие PDP `read` на `core:access:external-system` (администратор платформы, аудитор). Раздела больше нет в базе знаний — строка с `name: null` и `status: missing`; база знаний не ответила — `name: null`, `status: unknown`.

Параметры

ПолеТипОбязательноОписание
id (в адресе)string (uuid)да

Ответы

200. Выданные разделы

Поля ответа

ПолеТипОбязательноОписание
itemsobject[]да
items[].sectionIdstring (uuid)да
items[].namestring | nullда
items[].projectIdstring (uuid) | nullда
items[].projectNamestring | nullда
items[].statusstringда`missing` — раздела больше нет в базе знаний; `unknown` — база знаний не ответила. Значения: ok, missing, unknown.
items[].grantedBystringда
items[].grantedAtstring (date-time)да

403. Ошибка RFC 9457

404. Ошибка RFC 9457

503. Ошибка RFC 9457

Выдать внешней системе раздел базы знаний. Повторная выдача — 200 без нового события.

PUT /api/core/v1/external-systems/{id}/sections/{sectionId} операция grantExternalSystemSection

Канал staff; действие PDP `update` (только администратор платформы). Событие `access.external-system-section-granted` пишется той же транзакцией, что выдача. Ошибки: 404 `not-found` (системы нет); 422 `section-unknown` «Раздела базы знаний «{id}» на установке нет»; 503 `dependency-unavailable` «База знаний не ответила — изменение не выполнено. Повторите позже.» (выдача без проверки раздела не пишется).

Параметры

ПолеТипОбязательноОписание
id (в адресе)string (uuid)да
sectionId (в адресе)string (uuid)даРаздел базы знаний (`kb.section.id`).
X-BM-CSRF (заголовок)stringдаЗаголовок CSRF шлюза на изменяющих вызовах канала staff.

Ответы

200. Раздел выдан

Поля ответа

ПолеТипОбязательноОписание
sectionIdstring (uuid)да
namestring | nullда
projectIdstring (uuid) | nullда
projectNamestring | nullда
statusstringда`missing` — раздела больше нет в базе знаний; `unknown` — база знаний не ответила. Значения: ok, missing, unknown.
grantedBystringда
grantedAtstring (date-time)да

400. Ошибка RFC 9457

403. Ошибка RFC 9457

404. Ошибка RFC 9457

422. Ошибка RFC 9457

503. Ошибка RFC 9457

Отозвать у внешней системы раздел базы знаний. Невыданный — 204 без события.

DELETE /api/core/v1/external-systems/{id}/sections/{sectionId} операция revokeExternalSystemSection

Канал staff; действие PDP `update`. Событие `access.external-system-section-revoked`. Отзыв действует со следующего запуска помощника. База знаний не ответила — 503 `dependency-unavailable`, выдача остаётся.

Параметры

ПолеТипОбязательноОписание
id (в адресе)string (uuid)да
sectionId (в адресе)string (uuid)даРаздел базы знаний (`kb.section.id`).
X-BM-CSRF (заголовок)stringдаЗаголовок CSRF шлюза на изменяющих вызовах канала staff.

Ответы

204. Раздел отозван либо выдачи не было

400. Ошибка RFC 9457

403. Ошибка RFC 9457

404. Ошибка RFC 9457

503. Ошибка RFC 9457