Backend API: создание экзаменационных сессий и получение токенов

Эндпоинт

POST

https://api.trustexam.ai/api/external-session/assignment.json?api_token=YOUR_API_TOKEN

Также api_token можно передать в заголовках:

• Заголовок: X-Authorization: YOUR_API_TOKEN

Ответ (ключевое поле)

Из JSON-ответа вам нужен один обязательный блок для запуска прокторинга:

{
  "external_session": {
    "token": "..."
  },
  "report_url": "https://app.trustexam.ai/.../report"
}

{
  "external_session": {
    "token": "..."
  },
  "report_url": "https://app.trustexam.ai/.../report"
}

{
  "external_session": {
    "token": "..."
  },
  "report_url": "https://app.trustexam.ai/.../report"
}

• external_session.token – используется фронтенд-SDK.

• report_url – ссылка на отчёт о попытке в интерфейсе TrustExam.

Требуемая структура запроса

Тело запроса — JSON-объект, который как минимум содержит следующие разделы:

1. assignment (object) – обязательное

• assignment.external_id (string / int / mixed) – обязательное

  Уникальный идентификатор задания/экзамена в вашей системе.

  Примеры:

  • "platonus-2025-09-17"

  • "subject-math-101"

  Используется для:

  • группировки попыток,

  • обновления настроек экзамена без дублирования,

  • повторного использования одного и того же экзамена для разных студентов.

• assignment.name (string) – обязательное

  Название экзамена.

  Примеры:

  • "Экзамены за 2025-09-17"

  • "Финансовая грамотность"

• assignment.settings (object) – обязательное

  Содержит:

  • proctoring_settings – настройки прокторинга,

  • webhook – настройки веб-хуков (опционально).

2. student (object) – обязательное

• student.external_id (string / int / mixed) – обязательное

  Уникальный идентификатор пользователя в вашей системе.

  Если вы повторно отправите запрос с тем же student.external_id и assignment.external_id, TrustExam обновит данные, а не создаст дубликат.
  
  

• student.name (string) – обязательное

  ФИО студента.
  
  

• student.email (string) – рекомендуемое

  Для уведомлений и привязки аккаунта.

3. application (string) – обязательное

• Возможные значения: "desktop", "tray", "browser"

• По умолчанию: "browser"

  Определяет тип приложения, через которое будет проходить экзамен.
  
  

4. session_data (object) – опционально

• session_data.external_id (string / int / mixed)

  Идентификатор конкретной попытки в вашей системе.

  Возвращается в отчётах как:

  • assignment_attempt_external_id (формат Default), или

  • attemptId (формат HRTools).
    
    

Настройки веб-хуков (assignment.settings.webhook)

Можно настроить веб-хуки, чтобы получать события старта и завершения экзамена.

• webhook.report_type (string)

  По умолчанию: "Default"

  Возможные значения: "Default", "HRTools" (возможны кастомные форматы).
  
  

• webhook.start_url (string, необязательное)

  URL для отправки данных при старте экзамена.

  Пример: https://your-domain.com/webhook/start
  
  

• webhook.finish_url (string, необязательное)

  URL для отправки данных при завершении экзамена.

  Пример: https://your-domain.com/webhook/finish
  
  

• webhook.post (object, необязательное)

  Дополнительные параметры, которые будут добавлены в тело запроса веб-хука.

  Пример:

  {"course_id": 123, "instructor_id": 456}

  {"course_id": 123, "instructor_id": 456}

  {"course_id": 123, "instructor_id": 456}

• webhook.headers (object, необязательное)

  Дополнительные HTTP-заголовки для веб-хуков.

  Пример:

  {"Authorization": "Bearer token", "X-Custom-Header": "value"}

  {"Authorization": "Bearer token", "X-Custom-Header": "value"}

  {"Authorization": "Bearer token", "X-Custom-Header": "value"}

• webhook.query (object, необязательное)

  Дополнительные параметры в URL.

  Пример:

  {"version": "1.0", "format": "json"}

  {"version": "1.0", "format": "json"}

  {"version": "1.0", "format": "json"}

Резюме backend-процесса

1. Ваш backend отправляет в TrustExam данные о задании и студенте с нужными настройками.

2. В ответе вы получаете external_session.token и report_url.

3. Вы передаёте external_session.token во фронтенд и инициализируете Proctoring SDK.

4. События экзамена доступны через:

   • веб-хуки,

   • report_url,

   • API AI-отчётов.