Как получить список отчётов по тестированию через 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=ru' \
  -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=ru' \
  -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.