Як отримати список звітів з тестування через API

Коротка відповідь

Endpoint POST /api/v1/tests/reports/search повертає список звітів з тестування із застосуванням поточного збереженого фільтра. Усі поля request body необов’язкові; без body API використовує page = 0, size = 50, view = all. Для доступу потрібен Bearer token зі scope tests.read, а lang може керувати мовою локалізованих ресурсів тестування.

Який endpoint використовується?

Використовується POST /api/v1/tests/reports/search. Endpoint повертає сторінку звітів з тестування у межах компанії з урахуванням поточного збереженого фільтра.

Для чого використовується цей API endpoint?

Endpoint використовується для отримання звітів з тестування компанії з пагінацією, режимом представлення та пошуком по ПІБ. Його використовують HR-інтеграції, backend-сервіси та технічні адміністратори для побудови списків звітів і переходу до PDF-звітів.

Які передумови потрібні перед виконанням запиту?

• Потрібен Bearer token з company context.

• Token має містити scope tests.read.

• Перед отриманням потрібних даних потрібно врахувати поточний збережений фільтр або скинути його.

Які параметри потрібно передати в запиті?

Headers

Path parameters

Path parameters відсутні.

Query parameters

Request body

curl приклад

Приклад виклику без body:

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

Приклад виклику з параметрами:

curl -X POST 'https://smartway.pro/api/v1/tests/reports/search?lang=uk' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "page": 0,
    "size": 20,
    "view": "all",
    "query": "Іван"
  }'

Яку відповідь повертає API?

Успішний запит повертає 200 OK і об’єкт PublicTestReportListResponse зі списком звітів та метаданими пагінації.

{
  "data": [
    {
      "uniqueId": "abc12345",
      "candidateId": 1001,
      "name": "Іван Петренко",
      "dateSend": "2026-03-10",
      "dateReceipt": "2026-03-12",
      "active": true,
      "testNames": "Conflict Test, Adaptive Sales",
      "department": "Sales",
      "jobTitle": "Manager"
    }
  ],
  "meta": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "hasNext": false
  }
}

Що означають поля у відповіді API?

Що відбувається під капотом?

• Tenant-видимість звітів визначається server-side з companyId у Bearer token як company-level / HRADMIN-equivalent scope.

• Звітність не обмежується кандидатами, запрошеними через поточний API key або HR-власника ключа.

• API повертає всі звіти з тестування компанії, які доступні HRADMIN-рівню.

• Додатково застосовується поточний збережений фільтр із GET/PUT /api/v1/tests/reports/filter: active, startDate, endDate, testIds, departments, jobTitles.

• lang необов’язковий; якщо його не передати, API використовує en.

• Для доступу потрібен scope tests.read.

Які edge cases потрібно врахувати?

Які помилки може повернути API?

Як використовувати результат у наступних API-запитах?

Використовуйте meta.page, meta.size, meta.totalPages і meta.hasNext для пагінації. Значення uniqueId зі списку використовується для отримання PDF-звіту.

Приклад наступного запиту для отримання PDF-звіту:

curl -X GET 'https://smartway.pro/api/v1/tests/reports/pdf?uniqueId=abc12345&lang=uk' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/pdf' \
  --output test-report-abc12345.pdf

Яких помилок інтегратору варто уникати?

• Вважати page = 1 першою сторінкою.

• Не враховувати активний збережений фільтр перед пошуком.

• Передавати view, відмінний від all, candidate, employee.

• Очікувати, що API поверне тільки звіти кандидатів, запрошених через поточний API key.

FAQ

Чи обов’язково передавати request body?

Ні. Якщо викликати endpoint без body, API використовує page = 0, size = 50, view = all.

З якої сторінки починається пагінація?

Параметр page є 0-based: page = 0 — перша сторінка, page = 1 — друга.

Які значення підтримує view?

Допустимі лише all, candidate, employee.

Чи застосовується збережений фільтр?

Так. Додатково застосовується фільтр із GET/PUT /api/v1/tests/reports/filter.

Який scope потрібен?

Для доступу потрібен scope tests.read.