Услуги и каталог

Все методы · Ключи и права · Ошибки

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

Для методов с ключом действуют общие проверки: 401 — ключ не принят, 403 — не хватает scope или прав владельца, 429 — превышен лимит. Неверные параметры могут дать 400, недоступный адресный ресурс — 404. Особенности команды указаны рядом с методом. Точную причину смотрите в error.code и details: как обработать ошибку и безопасно повторить запрос.

Получить доступные услуги

GET /api/v1/services

Действие ключа: catalog:read. Оно не заменяет права владельца на объекты и поля.

locale по умолчанию ru-RU. Только услуги, доступные владельцу ключа.

Параметры пути: нет. Тело: не требуется.

Query-пример: locale=ru-RU.

Пример запроса

GET /api/v1/services?locale=ru-RU HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Массив услуг.

{
  "data": [],
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Прочитать услугу

GET /api/v1/services/{serviceId}

Действие ключа: catalog:read. Оно не заменяет права владельца на объекты и поля.

serviceId и locale; недоступная услуга не раскрывается.

Параметры пути: serviceId. Тело: не требуется.

Query-пример: locale=ru-RU.

Пример запроса

GET /api/v1/services/SERVICE_ID?locale=ru-RU HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Проекция услуги.

{
  "data": {
    "id": "SERVICE_ID",
    "name": "Услуга"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Прочитать каталог

GET /api/v1/catalog

Действие ключа: catalog:read. Оно не заменяет права владельца на объекты и поля.

locale по умолчанию ru-RU. Если активного каталога нет, data:null. Категории и элементы фильтруются по доступу.

Параметры пути: нет. Тело: не требуется.

Query-пример: locale=ru-RU.

Пример запроса

GET /api/v1/catalog?locale=ru-RU HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Каталог с categories/items либо null.

{
  "data": null,
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Создать обращение от пользователя

POST /api/v1/catalog/items/{itemId}/requests

Действие ключа: catalog:impersonate. Оно не заменяет права владельца на объекты и поля.

Делегированный сценарий: права и доступность элемента проверяются от requesterId. assetId необязателен. Не выдавайте catalog:impersonate обычной read-only интеграции.

Параметры пути: itemId. Тело: JSON; пример ниже показывает основные поля.

Поддерживает Idempotency-Key. См. безопасные повторы.

Пример запроса

POST /api/v1/catalog/items/ITEM_ID/requests HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: example-operation-001

{
  "requesterId": "USER_ID",
  "values": {
    "FIELD_CODE": "Значение"
  }
}

Ответ и ошибки

Успех: 201. Созданная заявка (проекция портала).

{
  "data": {
    "id": "OBJECT_ID"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Связанные статьи

• Обзор API
• Права доступа
• Интеграции