Как обновить или очистить фильтр отчётов по тестированию через 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-экспорта.

Какие предварительные условия нужны перед выполнением запроса?

• Нужен Bearer token.

• Token должен содержать scope tests.write.

Какие параметры нужно передать в запросе?

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.