Описание UserAPI ПО МТС Линк on-premise. Встречи

UserAPI для Встреч, Вебинаров и Курсов. Webhooks

UserAPI

Ключ

Для работы с UserAPI потребуется ключ авторизации и перечень запросов (методов).

Ключ — это авторизационный токен. Он доступен в подразделе «API/Webhooks» раздела «Бизнес» личного кабинета МТС Линк. Во всех запросах он передается в параметре x-auth-token.

Можно добавлять несколько ключей с разными доступами.

Для добавления ключа необходимо в разделе «Бизнес» личного кабинета МТС Линк перейти в подраздел «API/Webhooks» на вкладку «API» и нажать на кнопку «Добавить»:

Далее в поле «Интеграции» выбрать из выпадающего списка нужную (если нет подходящего варианта, необходимо выбрать «Другое»), в поле «Доступы» в выпадающем списке отметить нужные варианты.

Важно! Единовременно может храниться не более 20 ключей.

Набор выбранных доступов можно изменить в любое время без необходимости удалять или обновлять ключ. Для этого нужно нажать на троеточие справа от интеграции и выбрать «Редактировать». Там же можно удалить интеграцию:

Правила использования ключа

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

Ограничения

Количество запросов к пользовательскому API не может превышать двух в секунду.

При получении ответа

{"error":{"code":429, "message": "I only allow 2 requests per second. Try again."}}

следует снизить частоту запросов.

Ошибки

Общие ошибки:

400 — не переданы или переданы в неверном формате обязательные параметры;
401 — не передан или передан некорректный заголовок x-auth-token;
403 — переданный x-auth-token неактивен или не существует;
404 — передаваемая в заголовке сущность не найдена для этой Организации.

Ошибки при работе с мероприятиями:

409 Conflict — [для вебинаров] eventsession не может быть создана.
Для несерийного мероприятия: уже существует eventsession.
Для серийного мероприятия: уже есть eventsession на указанную дату и время;
403 Event owner is not submitted — у ownerid не подтверждена почта на платформе.

Ошибки при работе с Участниками:

400 ERROR_BLANK — [для регистраций] одно или несколько полей регистрации не указаны для Участника;
400 Date do not matches event rule — [для регистраций на серийные мероприятия] дата, на которую нужно зарегистрировать Участника, не соответствует правилу повторений этого мероприятия;
409 Conflict — Участник/контакт с таким email уже зарегистрирован.

Ошибки при работе со статистикой:

403 — пользователь, userid которого передан, не является членом Организации
404 — за указанный период не найдено ни одного мероприятия.

Ошибки при работе с файлами, тестами, записями:

409 — тест не может быть обновлен;
409 Event session is not started — [при старте теста] мероприятие не запущено;
409 Test not attached to Event session — [при старте теста] в мероприятии уже запущен тест;
409 Conflict — [при запуске конвертации] у этого пользователя уже запущена конвертация;
404 Test not attached to Event session — [при старте теста] тест не добавлен как файл к вебинару.

Ошибки при работе с курсами:

403 — пользователь не имеет доступа к API методам или ему запрещено создавать и отправлять приглашения;
404 — указанная группа не найдена;
400 — не указан список email адресов.

Пояснения к разделам

Раздел «Регистрация API»:

обязательно указывать все регистрационные поля;
(архивный способ передачи данных) в вебинары с настройкой «Премодерация» (access=8 и access=10) регистрация должна осуществляться с запросом на премодерацию, иначе Участники не будут одобрены;
ключи дополнительных полей ({FieldKey}) можно получить запросом GET /eventsessions/{SessionID};
для каждого Участника требуется уникальный email. При попытке зарегистрировать один email дважды в ответе будет ошибка 409 Conflict;
невозможно зарегистрировать Администратора команды как простого Участника в вебинары этой команды — его роль всегда будет admin.

Раздел «Адресная книга API»:

с помощью GET /contacts/{contactId} можно получить userid Участников для дальнейшего получения статистики по ним;
в список контактов попадают и те, кто добавлен через API, и те, кого Организатор вручную добавит в адресную книгу, и Участники, которые регистрировались на вебинары Организации.

Раздел «Тесты и голосования API»:

TestFile (тест). Сущность содержит в себе все настройки. Данная сущность так же является наследником сущности файла. Это позволяет применять к ней операции, доступные другим файлам (перемещать между папками, прикреплять к мероприятию).

Поля сущности:

id — уникальный идентификатор теста;
userid — ID пользователя, которому данный тест принадлежит;
name — название теста;
assessType — тип оценки результатов. Может быть:
pointsSum — по количеству баллов;
answerCount — по количеству правильных ответов;
minPoints — минимальное количество баллов, необходимое для успешного прохождения теста. Необязательное поле. Значение по умолчанию: 0;
minAnswers — минимальное количество правильных ответов, необходимое для успешного прохождения теста. Необязательное поле. Значение по умолчанию: 0;
duration — заявленная длительность теста в секундах. Используется для тестирования в режиме реального времени. Необязательное поле. Значение по умолчанию: 0;
questions — список вопросов теста.

TestQuestion (вопрос теста)
Поля сущности:

id — ID записи в БД. Уникальный идентификатор сущности;
questionData — текст вопроса. Обязательное поле;
questionImage — изображение. Если в вопросе используется изображение, в этом поле находится массив данных для изображения:
id — ID файла, используемого для изображения;
url — ссылка на скачивание изображения;
thumbnails — массив со ссылками на миниатюры изображения;
allowCustomAnswer — свободный ответ. Флаг, определяющий наличие или отсутствие в вопросе свободного ответа. Значение по умолчанию: false;
maxPointsAnswers — максимально возможное количество ответов с баллами, доступное в данном вопросе. Имеет смысл только в случае, если возможно выбрать одновременно несколько ответов. Значение по умолчанию: 1;
order — порядковый номер вопроса в списке;
answers — список ответов на данный вопрос.

TestQuestionAnswer (ответ на вопрос теста)
Поля сущности:

id — уникальный идентификатор ответа;
answerData — текст ответа на вопрос;
answerImage — если ответом на вопрос является изображение, то в этом поле находится массив с данными изображения:
id — ID файла, используемого для изображения;
url — ссылка на скачивание изображения;
thumbnails — массив со ссылками на миниатюры изображения;
isCorrect — флаг, отвечающий за правильность ответа. Необязательное поле. Значение по умолчанию: false;
points — количество баллов, получаемое за выбор данного ответа. Необязательное поле. Значение по умолчанию: 0;
order — порядковый номер ответа в списке.

TestSession (результаты проведенного теста или голосования). Всякий раз, когда запускается тест, создается сущность TestSession, где формируются данные об ответах. Каждая TestSession связана с мероприятием (eventSession), в котором была проведена.

Поля сущности:

id — уникальный идентификатор проведения теста/голосования;
eventSessionId — уникальный идентификатор вебинара (eventSession), в котором проводился тест;
startTime — время старта TestSession. Формат: YYYY-MM-DD HH:MM:SS;
endTime — время завершения TestSession. Формат: YYYY-MM-DD HH:MM:SS;
isComplexResultsShared — флаг, отвечающий за то, разрешено ли Участникам тестирования получить сводные результаты теста;
isIndividualResultsShared — флаг, отвечающий за то, разрешено ли Участникам тестирования получить индивидуальные результаты теста. Используется при тестировании в рамках мероприятия.

UserTestPassing (результаты прохождения теста Участника)

Поля сущности:

id — уникальный идентификатор результата;
questionCount — количество вопросов теста;
minPointsToPass — минимальное количество баллов, необходимое Участнику для успешного прохождения тестирования;
minCorrectAnswersToPass — минимальное количество правильных ответов, необходимое Участнику для успешного прохождения тестирования;
startTime — дата/время начала прохождения тестирования;
endTime — дата/время окончания прохождения тестирования;
isTestPassed — итог теста. Флаг показывает набрал ли Участник нужное количество баллов/правильных ответов;
answerCount — количество ответов, данных Участником;
pointsSum — сумма баллов, набранная Участником;
correctAnswerCount — количество вопросов, на которые был дан правильный ответ. Правильный ответ на вопрос подразумевает, что пользователь выбрал все ответы, которые отмечены как правильные в вопросе;
testSessionId — ID TestSession, в рамках которой Участник проходил тестирование;
userId — ID Участника, который проходил тестирование;
eventSessionId — ID мероприятия (eventSession), в рамках которого было проведено тестирование.

UserTestQuestionAnswer (один ответ Участника на один вопрос теста)

Параметры:

id — уникальный идентификатор ответа Участника;
questionData — текст вопроса;
questionImage — изображение вопроса. Если вопрос был с изображением, то в этом поле находиться массив с данными изображения:
id — ID файла, используемого для изображения;
url — ссылка на скачивание изображения;
thumbnails — массив со ссылками на миниатюры изображения;
answerData — текст ответа;
answerImage — изображение ответа. Если в качестве ответа было выбрано изображение, то в этом поле находиться массив с данными изображения:
id — ID файла, используемого для изображения;
url — ссылка на скачивание изображения;
thumbnails — массив со ссылками на миниатюры изображения;
isCorrect — итог теста. Флаг показывает набрал ли Участник нужное количество баллов/правильных ответов;
answerPoints — количество баллов за ответ;
isCustomAnswerSubmitted — флаг, показывающий, что ответ, данный Участником, является свободным, а не выбранным из предложенных;
isCustomAnswerAssessed — флаг, показывающий, что свободный ответ был оценен ведущим и ответу проставлены значения isCorrect и/или answerPoints;
userId — ID Участника, который дал ответ;
userTestPassingId — ID сущности UserTestPassing, в рамках которой пользователем был дан ответ.

Раздел «Записи API»:

в одну единицу времени может подготавливаться в MP4 (конвертироваться) только одна запись одного сотрудника Организации;
средняя продолжительность конвертации — 1-2 продолжительности самой записи;
ошибка 403 "message": "Simultaneous conversions quantity exceeded" означает, что превышен лимит одновременных конвертаций для Организации.

Раздел «Файлы API»:

Возвращаемые параметры:

id — идентификатор файла/папки;
parent — папка, в которой находится файл/папка. NULL — корневая папка;
isDeleted — флаг удаления файла/папки. Значения:
true — файл удален;
false — файл доступен в файловом менеджере;
createAt — дата создания/загрузки файла/папки;
name — имя файла/папки;
type — тип. Значения:
file — файл;
folder — папка;
user — Владелец файла/папки;
organization — принадлежность к Организации;
path — относительный путь файла. В пользовательских сценариях не используется;
url — полный путь файла;
downloadUrl — ссылка на скачивание файла. В пользовательских сценариях не используется;
thumbnailUrl — ссылка на миниатюру изображения. В пользовательских сценариях не используется;
thumbnails — миниатюры картинок;
size — размер файла в байтах;
format — расширение файла;
isHidden — доступность файла. В пользовательских сценариях не используется;
isSystem — принадлежность файла системе. В пользовательских сценариях не используется;
mimeType — MIME тип файла. В пользовательских сценариях не используется;
typeFile — тип файла. Подробнее о типах файлов и данных по ним ниже;
uri — uri файла. В пользовательских сценариях не используется;
thumbnailUri — ссылка на миниатюру изображения. В пользовательских сценариях не используется.

Типы файлов

Video (видеофайл). Может быть загруженным видео, а может быть Yotube/Vimeo.

Параметры:

duration — длительность видео;
description — описание. Для видео Yotube/Vimeo:
src — ссылка на видео;
author — имя автора видео;
authorUrl — канал автора на Yotube/Vimeo;
videoId — id видео на Vimeo.

Presentation (презентация)

Параметры:

state — состояние конвертации. Значения:
completed — выполнена;
failed — произошла ошибка при конвертации;
loaded — ожидает в очереди;
waiting — ожидает в очереди;
slides — набор слайдов. Доступны после конвертации.

Slide (слайд презентации)

Параметры:

number — порядок слайда;
rotate — угол поворота.

Test (тест)

Параметры:

duration — длительность теста/голосования;
minAnswers — минимальное количество ответов для того, чтобы пройти тест;
minPoints — минимальное количество баллов;
assessType — определяет, по какому критерию судить прохождение теста: minAnswers или minPoints;
contextType — тест/голосование;
questions — вопросы и ответы на них, либо голосование с вариантами ответа;
testResult — файл результатов теста.

Record (онлайн-запись)

Параметры:

duration — длительность видео;
description — описание;
cuts — поле, которое показывает вырезанные отрезки видео в записи. Определяются по полям start – end;
password — пароль на запись;
isViewable — открыта ли запись для общего доступа;
eventSession — принадлежность вебинару;
state — готовность записи.

ConvertedRecord (сконвертированная МР4-запись)

Параметры:

convertedAt — дата конвертации;
state — состояние конвертации;
progress — состояние конвертации в %.

Методы. Встречи и Вебинары

Важно! Во всех методах и примерах запросов часть значения URL «userapi.mts-link.ru/v3» (или вариации) должна быть заменена на «webinars.example.ru/api/userapi», где «webinars.example.ru» задается в соответствии с установочными настройками доменов (подробнее см. в «Руководстве по установке ПО МТС Линк on-premise. Встречи»).

Например:

URL: https://userapi.mts-link.ru/v3/events

примет вид

URL: https://webinars.example.ru/api/userapi/events

Методы. Курсы

Webhooks

Добавление

Webhooks позволяют получать уведомления о событиях, связанных с мероприятиями, в реальном времени. Они отправляются в формате JSON через HTTP-запросы (метод POST) на указанный URL.

Для добавления вебхука необходимо в разделе «Бизнес» личного кабинета МТС Линк перейти в подраздел «API/Webhooks», далее перейти на вкладку «Webhooks» и нажать на кнопку «Добавить»:

Ввести название, адрес и в выпадающем списке отметить нужные типы событий.

Если на клиентской стороне используется самоподписной сертификат или сертификат с отозванным корневым сертификатом, то может возникнуть ошибка валидации. Для игнорирования такой ошибки нужно включить функцию «Игнорировать ошибки SSL сертификата».

Проверка подлинности

Чтобы подтвердить, что webhook отправлен из МТС Линк, в заголовок HTTP запроса встроен код для проверки.

При создании нового вебхука можно задать поле «секретная фраза». Если для вебхука был задан секрет, то POST-запрос вебхука будет содержать подпись в заголовке X-Webhook-Signature. Подпись представляет собой код аутентификации (проверки подлинности) сообщения на основе хэша (HMAC) c алгоритмом SHA-256.

Для определения подлинности вебхука необходимо выполнить следующие действия:

1. Извлечь подпись из заголовка запроса.

2. Определить ожидаемую подпись для тела запроса, преобразовав его в JSON и вычислив HMAC SHA-256.

3. Сравнить подпись из заголовка запроса с ожидаемой подписью.

👆 На этом пока всё

Описание UserAPI ПО МТС Линк on-premise. Встречи

UserAPI

Ключ

Методы. Встречи и Вебинары

Методы. Курсы

Webhooks

Добавление

Рекомендации по использованию

Проверка подлинности