Головна 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
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.