Svaya / Документация / Программный интерфейс
Внешние системы
Здесь собраны адреса, параметры, поля запросов и коды ответов раздела «Внешние системы». Каждая операция описана отдельно, с таблицами полей.
Перечень внешних систем. Секрета в ответе нет.
GET /api/core/v1/external-systems
Канал staff; действие PDP `read` на `core:access:external-system` (администратор платформы, аудитор).
Ответы
200. Перечень
Поля ответа
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
items | object[] | да | |
items[].id | string (uuid) | да | |
items[].clientId | string | да | |
items[].title | string | да | |
items[].description | string | да | |
items[].packages | string[] | да | |
items[].assistants | string (uuid)[] | да | |
items[].capabilities | string[] | да | |
items[].enabled | boolean | да | |
items[].createdBy | string | да | |
items[].createdAt | string (date-time) | да | |
items[].updatedBy | string | да | |
items[].updatedAt | string (date-time) | да | |
items[].sections | object[] | нет | |
items[].sections[].sectionId | string (uuid) | да | |
items[].sections[].name | string | null | да |
403. Ошибка RFC 9457
Завести внешнюю систему. Секрет — в ответе один раз.
POST /api/core/v1/external-systems
Канал staff; действие PDP `create`. Клиент заводится в системе входа выключенным и включается последним, после записи строки. Секрет (32 случайных байта, base64url) нигде не пишется. Ошибки: 400 `validation-failed`; 403 `forbidden`; 422 `package-unknown` «Автоматизации «{id}» на платформе нет»; 503 `identity-unavailable` «Система входа не ответила — изменение не выполнено. Повторите позже.»
Параметры
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
X-BM-CSRF (заголовок) | string | да | Заголовок CSRF шлюза на изменяющих вызовах канала staff. |
Поля тела запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
title | string | да | |
description | string | нет | |
packages | string[] | да | Автоматизации установки, которые система вправе запускать. |
assistants | string (uuid)[] | нет | Помощники, которых система вправе запускать (блок C). |
capabilities | string[] | нет | `metrics` — чтение метрик установки (`getMonitoringFederate`). |
Ответы
201. Система заведена
Поля ответа
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
system | object | да | Внешняя система. Секрета здесь нет никогда. |
system.id | string (uuid) | да | |
system.clientId | string | да | |
system.title | string | да | |
system.description | string | да | |
system.packages | string[] | да | |
system.assistants | string (uuid)[] | да | |
system.capabilities | string[] | да | |
system.enabled | boolean | да | |
system.createdBy | string | да | |
system.createdAt | string (date-time) | да | |
system.updatedBy | string | да | |
system.updatedAt | string (date-time) | да | |
system.sections | object[] | нет | |
system.sections[].sectionId | string (uuid) | да | |
system.sections[].name | string | null | да | |
secret | string | да | Показывается один раз. |
tokenUrl | string | да | Внешний адрес выдачи токена системы входа (`perimeter.public_url` и путь realm; тот же, что у входа сотрудников). |
400. Ошибка RFC 9457
403. Ошибка RFC 9457
422. Ошибка RFC 9457
503. Ошибка RFC 9457
Изменить внешнюю систему (название, описание, разрешённые автоматизации, помощников, возможности)
PUT /api/core/v1/external-systems/{id}
Канал staff; действие PDP `update`. Ошибки: 400, 403, 404 `not-found`, 422 `package-unknown`.
Параметры
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id (в адресе) | string (uuid) | да | |
X-BM-CSRF (заголовок) | string | да | Заголовок CSRF шлюза на изменяющих вызовах канала staff. |
Поля тела запроса
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
title | string | да | |
description | string | нет | |
packages | string[] | да | Автоматизации установки, которые система вправе запускать. |
assistants | string (uuid)[] | нет | Помощники, которых система вправе запускать (блок C). |
capabilities | string[] | нет | `metrics` — чтение метрик установки (`getMonitoringFederate`). |
Ответы
200. Система изменена
Поля ответа
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id | string (uuid) | да | |
clientId | string | да | |
title | string | да | |
description | string | да | |
packages | string[] | да | |
assistants | string (uuid)[] | да | |
capabilities | string[] | да | |
enabled | boolean | да | |
createdBy | string | да | |
createdAt | string (date-time) | да | |
updatedBy | string | да | |
updatedAt | string (date-time) | да | |
sections | object[] | нет | |
sections[].sectionId | string (uuid) | да | |
sections[].name | string | null | да |
400. Ошибка RFC 9457
403. Ошибка RFC 9457
404. Ошибка RFC 9457
422. Ошибка RFC 9457
Отключить внешнюю систему. Уже выданный токен перестаёт проходить права не позже чем через 30 с.
POST /api/core/v1/external-systems/{id}:disable
Канал staff; действие PDP `update`. Клиент выключается в системе входа ДО записи строки; система входа не ответила — 503 `identity-unavailable`, ничего не изменено.
Параметры
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id (в адресе) | string (uuid) | да | |
X-BM-CSRF (заголовок) | string | да | Заголовок CSRF шлюза на изменяющих вызовах канала staff. |
Ответы
200. Система отключена
Поля ответа
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id | string (uuid) | да | |
clientId | string | да | |
title | string | да | |
description | string | да | |
packages | string[] | да | |
assistants | string (uuid)[] | да | |
capabilities | string[] | да | |
enabled | boolean | да | |
createdBy | string | да | |
createdAt | string (date-time) | да | |
updatedBy | string | да | |
updatedAt | string (date-time) | да | |
sections | object[] | нет | |
sections[].sectionId | string (uuid) | да | |
sections[].name | string | null | да |
403. Ошибка RFC 9457
404. Ошибка RFC 9457
503. Ошибка RFC 9457
Включить внешнюю систему
POST /api/core/v1/external-systems/{id}:enable
Канал staff; действие PDP `update`. Клиент включается в системе входа, затем строка получает `enabled = true`.
Параметры
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id (в адресе) | string (uuid) | да | |
X-BM-CSRF (заголовок) | string | да | Заголовок CSRF шлюза на изменяющих вызовах канала staff. |
Ответы
200. Система включена
Поля ответа
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id | string (uuid) | да | |
clientId | string | да | |
title | string | да | |
description | string | да | |
packages | string[] | да | |
assistants | string (uuid)[] | да | |
capabilities | string[] | да | |
enabled | boolean | да | |
createdBy | string | да | |
createdAt | string (date-time) | да | |
updatedBy | string | да | |
updatedAt | string (date-time) | да | |
sections | object[] | нет | |
sections[].sectionId | string (uuid) | да | |
sections[].name | string | null | да |
403. Ошибка RFC 9457
404. Ошибка RFC 9457
503. Ошибка RFC 9457
Заменить секрет внешней системы. Новый секрет — в ответе один раз.
POST /api/core/v1/external-systems/{id}:rotate-secret
Канал staff; действие PDP `update`. Прежний секрет перестаёт действовать сразу после ответа системы входа.
Параметры
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id (в адресе) | string (uuid) | да | |
X-BM-CSRF (заголовок) | string | да | Заголовок CSRF шлюза на изменяющих вызовах канала staff. |
Ответы
200. Секрет заменён
Поля ответа
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
secret | string | да | |
tokenUrl | string | да |
403. Ошибка RFC 9457
404. Ошибка RFC 9457
503. Ошибка RFC 9457
listExternalSystemSections
GET /api/core/v1/external-systems/{id}/sections
Канал staff; действие PDP `read` на `core:access:external-system` (администратор платформы, аудитор). Раздела больше нет в базе знаний — строка с `name: null` и `status: missing`; база знаний не ответила — `name: null`, `status: unknown`.
Параметры
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id (в адресе) | string (uuid) | да |
Ответы
200. Выданные разделы
Поля ответа
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
items | object[] | да | |
items[].sectionId | string (uuid) | да | |
items[].name | string | null | да | |
items[].projectId | string (uuid) | null | да | |
items[].projectName | string | null | да | |
items[].status | string | да | `missing` — раздела больше нет в базе знаний; `unknown` — база знаний не ответила. Значения: ok, missing, unknown. |
items[].grantedBy | string | да | |
items[].grantedAt | string (date-time) | да |
403. Ошибка RFC 9457
404. Ошибка RFC 9457
503. Ошибка RFC 9457
Выдать внешней системе раздел базы знаний. Повторная выдача — 200 без нового события.
PUT /api/core/v1/external-systems/{id}/sections/{sectionId}
Канал 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. Раздел выдан
Поля ответа
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
sectionId | string (uuid) | да | |
name | string | null | да | |
projectId | string (uuid) | null | да | |
projectName | string | null | да | |
status | string | да | `missing` — раздела больше нет в базе знаний; `unknown` — база знаний не ответила. Значения: ok, missing, unknown. |
grantedBy | string | да | |
grantedAt | string (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}
Канал 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