Главная API Как отправить сотрудникам приглашение на тестирование через API

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

Обновлено Apr 28, 2026

Endpoint POST /api/v1/tests/invitations/employees выполняет массовую рассылку сотрудникам приглашений на тестирование. В body нужно передать непустые массивы employeeIds и testIds. Параметр lang управляет языком писем-приглашений и языком ссылок на прохождение теста.

Какой endpoint используется?

Используется POST /api/v1/tests/invitations/employees. Endpoint отправляет приглашение на тестирование списку сотрудников.

Параметр Значение
Method POST
Endpoint /api/v1/tests/invitations/employees
Base URL [https://smartway.pro](https://smartway.pro)
Auth Bearer token
Content-Type application/json

Для чего используется этот API endpoint?

Endpoint используется для массовой рассылки приглашений на тестирование сотрудникам компании. Его применяют в HR-интеграциях, когда внешняя система имеет список сотрудников и список тестов.

Какие предварительные условия нужны перед выполнением запроса?

  • Нужен Bearer token с company context.

  • Token должен содержать scope tests.write.

  • Нужен хотя бы один employeeId в рамках текущей компании.

  • Нужен хотя бы один testId.

Предусловие Описание Обязательно
access_token Bearer token с company context Да
tests.write Scope для создания приглашений Да
employeeIds Список ID сотрудников Да
testIds Список ID тестов Да

Какие параметры нужно передать в запросе?

Headers

Header Тип Обязательно Описание
Authorization string Да Bearer token в формате Bearer <access_token>
Accept string Да application/json
Content-Type string Да application/json

Path parameters

Path parameters отсутствуют.

Query parameters

Параметр Тип Обязательно Описание
lang string Нет Язык приглашения. Поддерживаются uk, ru, en. Если параметр отсутствует или передано другое значение, сервер использует en.

Request body

Параметр Тип Обязательно Описание
employeeIds int64[] Да Список ID сотрудников; должен содержать хотя бы один элемент
testIds int64[] Да Список ID тестов; должен содержать хотя бы один элемент

curl-пример

curl -X POST 'https://smartway.pro/api/v1/tests/invitations/employees?lang=en' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "employeeIds": [101, 102],
    "testIds": [5, 200001]
  }'

Какой ответ возвращает API?

Успешный запрос возвращает 202 Accepted.

Что происходит под капотом?

  • idCompany не передаётся в body или query string: он будет получен из Bearer token.

  • hrEmail не передаётся внешним клиентом: он будет получен из Bearer token.

  • lang принимает только uk, ru, en; если параметр не передан или значение не поддерживается, приглашения отправляются на английском (en).

  • employeeIds и testIds должны содержать хотя бы один элемент.

  • Если хотя бы один employee отсутствует в рамках текущей компании, API возвращает 404 Not Found.

  • Для доступа нужен scope tests.write.

Какие edge cases нужно учитывать?

Сценарий Поведение API Что сделать интегратору
lang отсутствует или не поддерживается Сервер использует en Передавать uk, ru или en, если нужен конкретный язык
employeeIds пустой API возвращает 400 Bad Request Передавать хотя бы один employeeId
testIds пустой API возвращает 400 Bad Request Передавать хотя бы один testId
Хотя бы один сотрудник не найден в tenant-е API возвращает 404 Not Found Проверять, что все employeeIds принадлежат текущей компании

Какие ошибки может вернуть API?

HTTP status Описание
400 Bad Request Отсутствуют или пустые employeeIds / testIds
401 Unauthorized Отсутствует или невалидный Bearer token
403 Forbidden Недостаточно прав
404 Not Found Хотя бы один сотрудник не найден в рамках текущего tenant-а
500 Internal Server Error Неожиданная ошибка
503 Service Unavailable Сбой сервиса

Как использовать результат в следующих API-запросах?

Перед массовой рассылкой получите доступные testId через каталог тестов. В body передавайте сотрудников в employeeIds, а тесты — в testIds.

Пример получения каталога тестов:

curl -X GET 'https://smartway.pro/api/v1/tests' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Каких ошибок интегратору стоит избегать?

  • Передавать idCompany или hrEmail в body.

  • Передавать пустой employeeIds или testIds.

  • Передавать employeeIds, которые не принадлежат текущей компании.

  • Ожидать ошибку для неподдерживаемого lang, хотя API использует en.

  • Вызывать endpoint без scope tests.write.

FAQ

Какой status возвращается при успешной рассылке?

API возвращает 202 Accepted.

Нужно ли передавать idCompany?

Нет. idCompany будет получен из Bearer token.

Что будет, если один сотрудник не найден?

API вернёт 404 Not Found, если хотя бы один сотрудник не найден в рамках текущего tenant-а.

Какие массивы обязательны?

Обязательны непустые employeeIds и testIds.

Какой scope нужен?

Для доступа нужен scope tests.write.