Метод умного фильтра
| Метод | Адрес | Кто вызывает | Начинает сессию |
|---|---|---|---|
| Умный фильтр | GET /api/iblock/{код}/smartFilter | гость и вошедший | нет |
Метод тяжёлый (запросы по фасетному индексу), поэтому включается отдельно, только у каталога. Выключенный метод отвечает 404, и его нет в документации API этого инфоблока. У инфоблока с видимостью «Только свои» метода нет: счётчики по всем элементам открыли бы чужие данные.
Параметры умного фильтра
| Параметр | Что делает |
|---|---|
section | ID или код секции — область товаров; можно несколько через запятую. Не передан — весь инфоблок |
filter | выбранное покупателем, JSON-объект: {"properties": {"<ID свойства>": [<ID значения>]}, "price": {"from": 100, "to": 900}} |
sectionsRoot | от какой секции строить список sections; по умолчанию — дети section |
Фильтр на витрине по шагам
- Покупатель открыл раздел:
GET /smartFilter?section=pants— вся панель фильтра: свойства, значения со счётчиками, диапазон цен, подразделы. - Покупатель отметил значение или сдвинул цену: витрина снова вызывает
smartFilterсfilter, и панель обновляется (счётчики, недоступные значения). Список товаров запрашивается отдельно:GET /elementsс теми же условиями (Состав ответа). - Блок фильтра на любом уровне каталога обновляется одним запросом
smartFilter. ШапкаGET /sections/{код}от фильтра не зависит.
curl "https://example.ru/api/iblock/catalog/smartFilter?section=pants" Ответ умного фильтра
{
"data": {
"properties": [
{
"id": 5,
"code": "BRAND_REF",
"name": "Бренд",
"chpuCode": "brand_ref",
"sort": 200,
"displayType": "G",
"hint": "",
"values": [
{
"id": 1,
"value": "Фэшн рай",
"chpuCode": "feshn_ray",
"xmlId": "company2",
"description": "",
"parentId": null,
"sort": 200,
"count": 3
}
]
}
],
"prices": { "from": 1899, "to": 2199 },
"sections": []
}
} Ответ стенда, сокращён. data состоит из трёх блоков.
properties
Свойства, у которых в настройках секций включён флаг «Показывать в умном фильтре» (у нескольких секций section — объединение). В список попадают значения, которые встречаются у товаров области. Для каждого свойства:
| Поле | Что это |
|---|---|
id, code, name, sort | свойство Битрикса |
chpuCode | код для адреса страницы (транслитерация названия) |
displayType, hint | вид отображения и подсказка из штатной настройки умного фильтра |
values[] | значения: id (его передают в filter.properties), value, chpuCode, xmlId, description, parentId, sort, count |
Состав полей не настраивается. Порядок значений: списки, привязки и справочники — по сортировке, строки — по алфавиту.
count у значения
Зависит от режима счётчиков инфоблока:
| Режим | count |
|---|---|
| «Не считать» | ключа нет, самый быстрый |
| «По разделу» | по всем товарам области, без filter; один запрос на все свойства |
| «С учётом выбранного» | с учётом filter, кроме выбора в самом этом свойстве (как у штатного умного фильтра); самый тяжёлый режим |
prices
{"from": ..., "to": ...} — минимум и максимум цены; только у торгового каталога, по разрешённым пользователю типам цен. В режиме «с учётом выбранного» считается с filter без price.
sections
Только если у инфоблока есть секции: дети sectionsRoot (по умолчанию — дети section), один уровень, по набору «Секции» плюс count — товары секции под filter, без ограничения областью section. Секции с count = 0 выводятся, чтобы витрина показала их неактивными.
curl -G "https://example.ru/api/iblock/catalog/smartFilter" \
--data-urlencode "section=1" \
--data-urlencode "sectionsRoot=1" \
--data-urlencode 'filter={"properties":{"5":[1]}}' {
"data": {
"properties": [ ],
"prices": { "from": 899, "to": 2999 },
"sections": [
{ "id": 2, "code": "pantolety", "name": "Пантолеты", "parentId": 1, "depthLevel": 2, "count": 1 },
{ "id": 3, "code": "slippers", "name": "Тапочки", "parentId": 1, "depthLevel": 2, "count": 2 }
]
}
} (В примере properties и поля секций сокращены.)
Фасетный индекс
Метод строится на фасетном индексе каталога Битрикса. Если индекс сброшен или перестраивается (после выгрузки из 1С или правки свойств), ответ всё равно приходит: значения берутся из таблиц свойств, счётчики — «по разделу». Автоматическое восстановление индекса включается на вкладке «Магазин» («Восстанавливать фасетный индекс»).
Ошибки умного фильтра
| Статус | Когда |
|---|---|
| 404 | метод выключен для инфоблока (или инфоблок «Только свои»); секция из section не найдена («Секция … не найдена»); sectionsRoot не найдена |
| 400 | filter не JSON-объект; filter.properties или filter.price не объект |
{
"success": false,
"error": "Параметр filter: price должен быть объектом {\"from\": число, \"to\": число}"
} Где настраивается умный фильтр
Настройки модуля -> вкладка «Инфоблоки» -> инфоблок каталога -> таб «Секции и фильтр»:
| Опция | Что делает |
|---|---|
| «Умный фильтр (/smartFilter)» | включает метод |
| «Счётчики значений фильтра» | «Не считать», «По разделу» или «С учётом выбранного» |
Какие свойства попадают в фильтр — штатный флаг «Показывать в умном фильтре» у секций инфоблока (настройки свойств инфоблока в Битриксе). Типы цен, из которых берётся диапазон, и скрытие товаров без цены — вкладка «Магазин». Сохраняется кнопкой «Сохранить настройки инфоблока».
Кеш умного фильтра
Ответ кешируется по хешу параметров: слой «Умный фильтр» (свойства и секции), цены — слой «Цены и остатки», в ключ входят группы пользователя и типы цен. Сроки — Настройки модуля -> «Кеширование», у инфоблока можно задать свой срок на табе «Кеш». Тег iblock_id_{ID} сбрасывается при изменении секции или элемента. Подробнее — Кеш.
Что почитать после умного фильтра
- Секции инфоблока
- Состав ответа: список товаров по тем же условиям
- Кеш