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

Endpoint PUT /api/v1/tests/reports/filter оновлює або очищає збережений фільтр звітів з тестування. У request body можна передати active, діапазон дат, groupByName, testIds, departments і jobTitles; якщо передати {} або body лише з null/порожніми колекціями, сервер очищає фільтр. Для доступу потрібен Bearer token зі scope tests.write.

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

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

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

Endpoint використовується для керування фільтром, який застосовується до пошуку та експорту звітів з тестування. Його використовують перед отриманням списку звітів або перед формуванням Excel-експорту.

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

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

Headers

Path parameters

Path parameters відсутні.

Query parameters

Query parameters відсутні.

Request body

curl приклад

Приклад виклику з оновленням фільтра:

curl -X PUT 'https://smartway.pro/api/v1/tests/reports/filter' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "active": true,
    "startDate": "2026-03-01",
    "endDate": "2026-03-10",
    "groupByName": true,
    "testIds": [5, 200001],
    "departments": ["Sales"],
    "jobTitles": ["Manager"]
  }'

Приклад виклику для очищення фільтра:

curl -X PUT 'https://smartway.pro/api/v1/tests/reports/filter' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'

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

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

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

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

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

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

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

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

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

• Якщо передати порожній об’єкт {} або body лише з null/порожніми колекціями, сервер очищає фільтр.

• Якщо endDate < startDate, API повертає 400 Bad Request.

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

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

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

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

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

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

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

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

• Передавати idUser у request body або query string.

• Передавати endDate, менший за startDate.

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

• Забувати, що порожній {} очищає фільтр.

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

FAQ

Як очистити фільтр?

Передайте порожній JSON-об’єкт {} або body лише з null/порожніми колекціями.

Що буде, якщо endDate < startDate?

API поверне 400 Bad Request.

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

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

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

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

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

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