External API

Внешние (относительно контура SmartCPD) API

Авторизация#

Доступ к внешним API возможен только при настроенном при установке API токене.

Для доступа ко всем методам API необходимо добавить заголовок: Authorization: Bearer API_TOKEN, где API_TOKEN - токен, созданный при установке/настройке решения.

Prometheus API#

Доступ к метрикам SmartCPD за пределами контура по URL портала и пути /prometheus/ с авторизацией заданным при установке токеном API: Authorization: Bearer API_TOKEN.

Пример:

curl -ik \
-H "Authorization: Bearer API_TOKEN" \
https://portal.fqdn/prometheus/api/v1/query?query=up

Markup API#

Загрузка разметки вызовов операторами.

Доступ к API за пределами контура по URL портала и пути /api/markup/ с авторизацией заданным при установке токеном API: Authorization: Bearer API_TOKEN.

Методы#

health#

Доступность сервиса

Запрос

GET api/markup/health

Ответы

• 200/OK сервис доступен

Пример

curl -ik \
-H "Authorization: Bearer API_TOKEN" \
https://portal.fqdn/api/markup/health

upload#

Пакетная загрузка разметки. Записи обрабатываются последовательно: при ошибке запроса конкретная запись попадает в список rejected, при внутренней ошибке обработка прекращается, а оставшиеся возвращаются в unprocessed.

Запрос

POST api/markup/v1/records

Заголовки

Тело запроса

Массив объектов MarkupUploadRecord. Минимальное содержимое:

[
  {
    "call_id": "51f737c0-4de5-0139-ba9f-0ac31e3255d2",
    "call_id_type": "sip",
    "ts": "2023-02-14T11:29:05Z",
    "result": "human",
    "original_result": "человек принял звонок"
  }
]

Возможные результаты:

• human - человек
• robot - робот
• ivr - ivr или голосовая почта
• silence - тишина, сброс инициирован Агентом
• remote_release - сброс инициирован абонентом, при этом невозможно классифицировать сторону абонента
• mav - оповещение о запрете массового обзвона

результаты классификации human и robot обязательные и используются для обучения системы детекции, прочие результаты опциональны и используются для отображения в статистике

Ответы

Тело ответа описывается моделью MarkupUploadResponse:

• last_uploaded — последняя успешно обработанная запись (MarkupUploadRecord).
• rejected — массив записей MarkupUploadRecord, отвергнутых из‑за ошибок в данных.
• unprocessed — массив записей MarkupUploadRecord, которые не успели попасть в обработку из‑за сбоя сервиса.

📡 IDM Integration API#

Реализует REST API для взаимодействия с системой управления пользователями (IDM) внутри on-premise инфраструктуры. Предоставляет методы для управления учетными записями сотрудников, получения ролей и привилегий.

Доступ по URL портала и пути /api/v1.0/idm-integration/ c авторизацией заданным при установке токеном API: Authorization: Bearer API_TOKEN.

Пример:

curl -ik \
-H "Authorization: Bearer API_TOKEN" \
https://portal.fqdn/api/v1.0/idm-integration/users

📦 Основные возможности#

• Получение списка всех пользователей, с их ролями и привилегиями
• Получение списка всех ролей с их привилегиями
• Создание сотрудника
• Обновление атрибутов сотрудника (кроме пароля и некоторых других)
• Блокировка/разблокировка сотрудника по логину (email)
• Изменение пароля сотрудника по email/password

🗂️ Структура данных#

Модель Role#

• id: Уникальный идентификатор роли
• name: Уникальное имя роли (например, admin)
• privileges: Список полномочий, предоставляемых ролью (например, ["employee.canEdit", "employee.canView"])

📘 API Методы#

🔍 Получение всех пользователей#

GET /api/v1.0/idm-integration/users

Ответ:

[
  {
    "login": "user@example.com",
    "name": "Иванов Иван Иванович",
    "status": "active",
    "roles": ["admin"],
    "privileges": ["employee.canSee", "employee.canEdit"]
  }
]

В привилегиях указываются все привилегии пользователя. Статус может быть одним из active, not_active, banned (постоянная блокировка, но её можно снять), temporary_banned (временная блокировка, условно, на 30 минут). В случае статуса banned пользователь не может зайти в систему. В случае temporary_banned – временно не может, если время с последней неуспешной попытки входа меньше заданного.

🎭 Получение всех ролей#

GET /api/v1.0/idm-integration/roles

Ответ: Список объектов Role в JSON-формате.

[
  {"id": 21, "name": "admin", "privileges": [
    "audit.canSee", "billing.canSee", "employee.canSee", "employee.canEdit", "employee.password.canEdit",
    "detectionSetting.canSee", "detectionSetting.canEdit", "license.canSee", "license.canEdit", "legalPerson.canEdit",
    "mlModel.canSee", "mlModel.canEdit", "setting.canSee", "setting.canEdit", "sip.canSee", "sip.canEdit", "statistic.canSee",
    "role.canSee", "role.canEdit", "security.canSee", "security.canEdit"
  ]},
  {"id": 23, "name": "analytic", "privileges": ["statistic.canSee", "role.canSee", "mlModel.canEdit", "mlModel.canSee", "security.canEdit", "sip.canEdit", "sip.canSee"]},
  {"id": 22, "name": "billing", "privileges": ["setting.canEdit", "sip.canEdit", "mlModel.canEdit"]}]

➕ Создание нового сотрудника#

POST /api/v1.0/idm-integration/employee

Тело запроса:

{
  "username": "Иванов Иван",
  "email": "user@example.com",
  "tel": "79999999999",
  "password": "<sha512 hash>",
  "agreed": true,
  "email_deal": true,
  "roles": ["admin", "support"]
}

username - это имя сотрудника. email – его логин. password здесь и в методе смены пароля передается в зашифрованном виде, а именно, в sha512. roles можно посмотреть через метод получения ролей.

🛠️ Обновление сотрудника#

PATCH /api/v1.0/idm-integration/employee

Достаточно передать только нужные для изменения поля:

{
  "login": "user@example.com",
  "username": "Иванов Петр",
  "tel": "79999999998",
  "roles": ["support"],
  "employee_status": "banned"
}

Поиск сотрудника идёт по login. Примечание: Некоторые поля защищены от изменений (password, salt, и др.).

Особенности:

• При изменении роли проверяется, не исчезнет ли привилегия role.canEdit и role.canSee у всех пользователей системы.

🔒 Блокировка сотрудника#

POST /api/v1.0/idm-integration/employee/block

Тело запроса:

{ "login": "user@example.com" }

🔓 Разблокировка сотрудника#

POST /api/v1.0/idm-integration/employee/unblock

Тело запроса:

{ "login": "user@example.com" }

🔑 Сброс пароля#

POST /api/v1.0/idm-integration/employee/password

Тело запроса:

{
  "login": "user@example.com",
  "password": "<sha512 hash>"
}

password здесь и в методе смены пароля передается в зашифрованном виде, а именно, в sha512.

📋 Аудит и безопасность#

• Некоторые изменения (например, изменение ролей или пароля) логируются в БД.
• После создания/обновления пароля сотрудник должен его сменить при 1-м входе в систему.