Фильтрация: общая структура запроса

Все эндпоинты фильтрации (POST .../filter) принимают единообразное тело запроса. На этой странице описана его структура и правила валидации — специфичные для каждого эндпоинта фильтры смотрите в документации соответствующего метода.

Request Body

Уровень 1	Уровень 2	Тип	Обязательное	Описание
filters		array[obj]	Нет	Массив условий фильтрации
	name	string	Да	Ключ фильтра. Допустимые значения зависят от эндпоинта
	value	any	Да	Значение фильтра. Тип зависит от конкретного ключа (см. ниже)
pagination		object	Нет	Управление постраничной навигацией
	limit	number	Нет	Количество записей на странице (стандартно 20)
	lastId	string | number | null	Нет	ID последнего элемента предыдущей страницы. null для первой страницы
order		array[obj]	Нет	Условия сортировки
	field	string	Да	Поле сортировки. Допустимые значения зависят от эндпоинта
	sort	string	Да	Направление: ASC или DESC
query		string	Нет	Текстовый поиск (поддерживается не всеми эндпоинтами)

Поля order и query поддерживаются не всеми эндпоинтами — наличие указано в документации конкретного метода.

Типы значений фильтров

Каждый ключ фильтра принимает value строго определённого типа. Для списочных типов (строки, числа) допустимо передавать как массив, так и одиночное значение — они равнозначны:

Тип	Формат value	Пример
Список строк	array[string] или string	["5f2d2604af74f046a9a86844", "5f2d2643af74f046a9a86846"]
Список строк (enum)	array[string] или string	["COMPLETED", "REJECTED"]
Список чисел	array[number] или number	[812, 759]
Диапазон дат	{"from": "ISO 8601", "to": "ISO 8601"}	{"from": "2026-01-01T00:00:00.000Z", "to": "2026-01-31T23:59:59.999Z"}
Диапазон чисел	{"from": number, "to": number}	{"from": 10000, "to": 100000}
Boolean	boolean	true

Правила валидации

Поле	Правило
filters[].name	Должно быть одним из допустимых ключей для данного эндпоинта. Недопустимое значение возвращает 400
filters[].value (enum)	Каждый элемент массива должен быть допустимым значением соответствующего статуса
filters[].value (строки)	Каждый элемент массива должен быть строкой
filters[].value (числа)	Каждый элемент массива должен быть конечным числом
filters[].value (диапазон дат)	from и to — строки в формате ISO 8601. Если переданы оба, from должно быть ≤ to
filters[].value (диапазон чисел)	from и to — числа. Если переданы оба, from должно быть ≤ to
pagination.limit	Целое число

Пагинация

Эндпоинты используют курсорную пагинацию на основе lastId:

1. В первом запросе передайте "lastId": null
2. В ответе будет поле result.lastId — ID последнего элемента в возвращённом списке
3. Для получения следующей страницы передайте это значение в pagination.lastId
4. Если result.lastId в ответе отсутствует или равен null — страниц больше нет

Пример запроса

curl --location "https://b2b.selfwork.ru/openapi/v2/organisation/550e8400-e29b-41d4-a716-446655440000/deals/filter" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ВАШ_API_КЛЮЧ" \
--data '{
    "filters": [
        {
            "name": "STATUS",
            "value": ["COMPLETED", "PAYMENT_IN_PROGRESS"]
        },
        {
            "name": "ANNOUNCEMENT_ID",
            "value": [654, 936]
        },
        {
            "name": "CREATED_AT",
            "value": {
                "from": "2026-01-01T00:00:00.000Z",
                "to": "2026-01-31T23:59:59.999Z"
            }
        },
        {
            "name": "AMOUNT",
            "value": {
                "from": 10000,
                "to": 100000
            }
        }
    ],
    "order": [
        { "field": "createdAt", "sort": "DESC" }
    ],
    "pagination": {
        "limit": 20,
        "lastId": null
    }
}'