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

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

Программный интерфейс: обзор и вход

Редакция 24 сентября 2026, дополнена 9 ноября 2026

Программный интерфейс нужен, чтобы ваша система сама запускала автоматизации платформы, читала их результат, забирала метрики и обращалась к языковым моделям по ключу доступа. Страницы этой группы собраны из договоров интерфейса, поэтому в них те же адреса, поля и коды ответов, что и в самой платформе.

Что можно делать

  • Процессы и задания: поставить задание, прочитать его состояние и результат, отменить его, передать сигнал ожидающему шагу.
  • Модели: обратиться к языковой модели и получить векторы текстов в привычном формате обращений к моделям: приложению достаточно сменить адрес и ключ.
  • Метрики: забрать метрики установки в систему наблюдения вашей компании.
  • Внешние системы: завести систему-отправителя заданий и выдать ей права.

Получение токена

Внешняя система входит под своим именем. Администратор заводит ее в кабинете на экране «Внешние системы»: платформа показывает идентификатор вида ext-xxxxxxxx, секрет и адрес выдачи токена. Секрет показывается один раз, сохраните его сразу. Токен выдается по схеме client credentials (OAuth 2.0):

Получение токена
curl -s -X POST "<адрес выдачи токена>" \
  -d grant_type=client_credentials \
  -d client_id=ext-xxxxxxxx \
  -d client_secret="<секрет>"

В ответе поле access_token и срок жизни expires_in в секундах. Токен держат до конца срока и запрашивают заново, когда он истек. Права системы ограничены тем, что разрешил администратор: списком автоматизаций, помощников и возможностями вроде чтения метрик. Запрос за пределами прав получает отказ 403.

Обращения к моделям идут не по токену, а по ключу доступа организации: ключ передается в заголовке Authorization: Bearer и выдается на экране ключей доступа.

Заголовки запросов

ЗаголовокКогда нуженНазначение
Authorization: Bearer <токен>ВсегдаТокен внешней системы или ключ доступа к моделям.
Content-Type: application/jsonЗапросы с теломТело всех операций передается в формате JSON.
Idempotency-KeyПостановка заданияЛюбая уникальная строка. Повтор запроса с тем же значением не создает второго задания, в ответе приходит то же задание и признак deduplicated.
traceparentПо желаниюЗаголовок трассировки W3C: по нему запрос находят в записях хода запусков.

Формат ошибок

Ошибки интерфейса платформы приходят с типом application/problem+json по RFC 9457. Код ответа протокола HTTP повторяется в поле status.

ПолеОписание
typeАдрес типа ошибки: по нему программа отличает одну ошибку от другой.
titleКороткое описание типа ошибки.
statusКод ответа HTTP.
detailПояснение к конкретному случаю.
trace_idИдентификатор трассы: назовите его, когда обращаетесь за помощью.

Обращения к моделям отвечают иначе: тело ошибки имеет вид {"error": {...}}, как принято в совместимом формате, и готовые клиентские библиотеки разбирают его сами.

Запуск задания и чтение результата

Запуск идет в два шага: поставить задание и читать его состояние, пока оно не завершится. Образец ниже ставит задание от имени внешней системы.

Постановка задания
curl -s -X POST "https://<адрес установки>/api/core/v1/processes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: zakaz-10542" \
  -d '{
    "packageId": "<идентификатор пакета>",
    "packageVersion": "<версия пакета>",
    "routeId": "<идентификатор маршрута>",
    "input": { "orderId": "10542" },
    "subject": { "id": "ext-xxxxxxxx", "class": "service" },
    "channel": "service"
  }'

Ответ 201 содержит processId. Состояние читается запросом GET /api/core/v1/processes/<идентификатор задания>. Поле status проходит значения от running до completed, failed или cancelled. Когда задание завершилось, поле result содержит итог:

Ответ на чтение задания
{
  "id": "<идентификатор задания>",
  "status": "completed",
  "result": {
    "outcome": "<код итога>",
    "title": "<название итога>",
    "data": { "...": "поля, которые объявил маршрут" }
  }
}

Данные итога лежат в result.data. Если они не помещаются в предел 65 536 байт, поле data пусто, а result.dataTruncated равно true. Полный перечень полей, значений и ответов - на странице «Процессы и задания».