Головна API документація Як отримати збережений фільтр звітів з тестування через API

Як отримати збережений фільтр звітів з тестування через API

Востаннє оновлено Apr 28, 2026

Endpoint GET /api/v1/tests/reports/filter повертає збережений фільтр звітів з тестування для userKey, який береться із subject Bearer token. Для company API key цей userKey має формат company-api-key:{companyId} і залишається стабільним після ротації ключа. Для доступу потрібен Bearer token зі scope tests.read.

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

Використовується GET /api/v1/tests/reports/filter. Endpoint повертає поточний збережений фільтр звітів з тестування для user context з Bearer token.

Параметр Значення
Method GET
Endpoint /api/v1/tests/reports/filter
Base URL https://smartway.pro
Auth Bearer token

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

Endpoint використовується для перегляду поточного фільтра, який застосовується до пошуку та експорту звітів з тестування. Його використовують перед POST /api/v1/tests/reports/search або POST /api/v1/tests/reports/export, щоб зрозуміти, які обмеження будуть застосовані.

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

Передумова Опис Обов’язково
access_token Bearer token Так
tests.read Scope для читання збереженого фільтра Так

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

Headers

Header Тип Обов’язково Опис
Authorization string Так Bearer token у форматі Bearer <access_token>
Accept string Так application/json

Path parameters

Path parameters відсутні.

Query parameters

Query parameters відсутні.

Request body

Request body не використовується.

curl приклад

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

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

Успішний запит повертає 200 OK і об’єкт PublicTestReportFilterResponse з параметрами збереженого фільтра.

{
  "active": true,
  "startDate": "2026-03-01",
  "endDate": "2026-03-10",
  "groupByName": true,
  "testIds": [5, 200001],
  "departments": ["Sales"],
  "jobTitles": ["Manager"]
}

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

Поле Тип Опис
active boolean Фільтр за ознакою активності звіту
startDate string Початок діапазону дат
endDate string Кінець діапазону дат
groupByName boolean Групування кількох спроб проходження тесту
testIds array Набір ID тестів для фільтра
departments array Набір департаментів для фільтра
jobTitles array Набір посад для фільтра

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

  • Фільтр прив’язаний до userKey, який береться із subject Bearer token.

  • Для company API key userKey має формат company-api-key:{companyId}.

  • userKey стабільний після ротації ключа.

  • Зовнішній клієнт не передає idUser.

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

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

Сценарій Поведінка API Що зробити інтегратору
Ротація company API key userKey залишається стабільним у форматі company-api-key:{companyId} Не створювати окрему прив’язку до active key id
idUser у запиті Зовнішній клієнт не передає idUser Не додавати idUser у query string або body
Активний збережений фільтр Фільтр застосовується до пошуку та експорту Перевіряти фільтр перед отриманням звітів

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

HTTP status Опис
401 Unauthorized Відсутній або невалідний Bearer token
403 Forbidden Недостатньо прав
500 Internal Server Error Неочікувана помилка
503 Service Unavailable Збій сервісу

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

Використовуйте отриманий фільтр, щоб зрозуміти, які обмеження будуть застосовані до POST /api/v1/tests/reports/search і POST /api/v1/tests/reports/export.

Приклад пошуку звітів після перевірки фільтра:

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

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

  • Передавати idUser у запиті.

  • Очікувати, що фільтр прив’язаний до конкретного active key id.

  • Запускати пошук або експорт без перевірки поточного фільтра.

  • Викликати endpoint без scope tests.read.

FAQ

До чого прив’язаний збережений фільтр?

Фільтр прив’язаний до userKey, який береться із subject Bearer token.

Який формат userKey для company API key?

Для company API key userKey має формат company-api-key:{companyId}.

Чи потрібно передавати idUser?

Ні. Зовнішній клієнт не передає idUser.

Чи зміниться фільтр після ротації ключа?

Для company API key userKey стабільний після ротації ключа.

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

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