Правила контракта:
/sections/{ID или код}— всегда одна секция, без детей;/sections— всегда список или дерево;- ключи ответа — camelCase, логические значения —
"Y"/"N".
Методы секций
| Метод | Адрес | Кто вызывает | Начинает сессию | Нагрузка |
|---|---|---|---|---|
| Секция с деталями | GET /api/iblock/{код}/sections/{ID или код} | гость и вошедший | нет | лёгкий |
| Список или дерево | GET /api/iblock/{код}/sections | гость и вошедший | нет | лёгкий |
| Дерево с количеством | GET /api/iblock/{код}/sections?withCount=Y | гость и вошедший | нет | один сгруппированный запрос |
| Дерево с элементами | GET /api/iblock/{код}/sections?withElements=Y | гость и вошедший | нет | один запрос элементов на ответ |
Методы включаются на табе «Секции и фильтр» инфоблока: выключенный отвечает 404. Тяжёлые добавки withCount и withElements администратор разрешает отдельно, по умолчанию они выключены.
Секции на витрине: меню и страница раздела
- Меню и плитки разделов:
GET /sections?depth=2— дерево на два уровня. - Мегаменю с числом товаров:
GET /sections?depth=2&withCount=Y. - Страница раздела: шапка —
GET /sections/{код}(название, описание, путь для хлебных крошек, SEO); подразделы —GET /sections?parent={код}; товары —GET /elements?sectionID=...(Состав ответа); блок фильтра —GET /smartFilter?section={код}(Умный фильтр). - Меню «Покупателям» из инфоблока страниц:
GET /sections?depth=0&withElements=Y— секции с вложенными страницами.
Секция: GET /sections/{ID или код}
curl "https://example.ru/api/iblock/catalog/sections/pants" {
"data": {
"id": 8,
"sort": 200,
"name": "Штаны",
"description": null,
"code": "pants",
"picture": "/upload/iblock/c5a/b2sx4sbhviiw85a2apuo4hrgcp4xgmdg.jpg",
"detailPicture": null,
"userFields": {
"ufBrowserTitle": { "value": null },
"ufKeywords": { "value": null }
},
"path": [
{ "id": 8, "code": "pants", "name": "Штаны" }
],
"seo": {
"h1": "Штаны",
"title": "Каталог Штаны от магазина Одежда+",
"keywords": "Штаны, купить Штаны",
"description": "..."
}
}
} Ответ стенда, сокращён. Состав полей — набор «Секция». path — от корня до секции (для хлебных крошек), seo — наследуемые SEO-поля секции (с учётом события OnAfterIblockSectionSeo, см. События). Секции нет — 404 «Секция не найдена».
Список и дерево: GET /sections
| Параметр | Что делает |
|---|---|
parent | ID или код родительской секции; не передан — корень инфоблока |
depth | 1 — плоский список детей parent (по умолчанию), N — дерево на N уровней, 0 — все уровни. Не целое число или меньше 0 — 400 |
order | сортировка, JSON-объект: {"sort":"asc"}; поля sort, name, id, code, направление asc / desc; по умолчанию по sort |
withCount | Y — добавить count: активные элементы секции вместе с подсекциями |
withElements | Y — добавить elements: активные элементы секций |
filter | фильтр элементов, как у /elements; только вместе с withCount=Y |
Выводятся активные секции. Состав полей — набор «Секции» (без path и seo). Структура секций читается одним запросом и кешируется; parent, depth и order применяются в памяти.
curl "https://example.ru/api/iblock/catalog/sections?depth=2&withCount=Y" {
"data": [
{
"id": 1,
"sort": 50,
"name": "Обувь",
"code": "shoes",
"parentId": null,
"depthLevel": 1,
"picture": "/upload/iblock/720/4em2wjkotpfy6ft4r7madgrn0f39nat4.jpg",
"detailPicture": null,
"userFields": {
"ufBrowserTitle": { "value": null }
},
"count": 7,
"children": [
{
"id": 2,
"name": "Пантолеты",
"code": "pantolety",
"parentId": 1,
"depthLevel": 2,
"count": 1,
"children": []
}
]
}
]
} Ответ стенда, сокращён. children — вложенные секции до depth.
withCount: количество элементов
Один сгруппированный запрос на инфоблок и фильтр; кешируется слоем «Секции и количество». С filter пустые секции не выводятся — пример: «секции акции»:
curl -G "https://example.ru/api/iblock/catalog/sections" \
--data-urlencode "withCount=Y" \
--data-urlencode 'filter={"properties":{"41":[61]}}' Без filter запрос лёгкий; на каталоге с сотнями тысяч товаров и фильтром по свойствам он заметно тяжелее.
withElements: секции с элементами
Для инфоблоков страниц, меню, документов; для каталога не включайте. Элементы приходят по набору «Вложенный» в порядке сортировки; элементы без секции — в meta.rootElements (если parent — корень).
{
"data": [
{
"id": 1590,
"code": "pokupatelyam",
"name": "Покупателям",
"userFields": { "ufHideHeader": { "value": "N" } },
"elements": [ { "id": 77, "code": "dostavka", "name": "Доставка" } ],
"children": []
}
],
"meta": {
"rootElements": [ { "id": 80, "code": "kontakty", "name": "Контакты" } ]
}
} Один запрос элементов на ответ, но размер ответа растёт с их числом. Предел элементов (по умолчанию 200) проверяется до сборки: больше — 400 «элементов больше предела», нужно сузить parent или depth.
Пользовательские поля секций
Поля секции типа UF приходят в userFields.{имя в camelCase}.value. Значение зависит от типа: строка, число, файл {src}, список {id, value, xmlId}, «Да/Нет» — "Y" / "N", привязка к элементам — элемент по набору «Вложенный» его инфоблока.
Ошибки методов секций
| Статус | Когда |
|---|---|
| 404 | инфоблок не открыт для API; метод выключен; секция {ID или код} или parent не найдена |
| 400 | depth не целое число или меньше 0; withCount / withElements не разрешён для инфоблока («Параметр withElements не разрешён для инфоблока catalog»); filter без withCount=Y; order или filter не JSON-объект; поле или направление order не поддерживается; превышен предел withElements |
Логические параметры принимают только Y / N: любое другое значение (true, 1) — тоже 400 «Параметр withCount: ожидается Y или N».
{
"success": false,
"error": "Параметр withElements не разрешён для инфоблока catalog"
} Где настраиваются методы секций
Настройки модуля -> вкладка «Инфоблоки» -> инфоблок -> таб «Секции и фильтр» -> «Методы секций»:
| Опция | Что делает |
|---|---|
| «Количество у секций (withCount)» | разрешает withCount=Y |
| «Элементы секций (withElements)» | разрешает withElements=Y |
| «Предел элементов» | сколько элементов допустимо отдать за один запрос, по умолчанию 200 |
Сохраняется кнопкой «Сохранить настройки инфоблока»; таблица маршрутов сбрасывается автоматически. Состав полей секций — наборы «Секция» (карточка) и «Секции» (список и дерево) на табе «Элементы» того же инфоблока: чипы групп «Поля», «Пользовательские поля», «Служебное» (путь и SEO только у набора «Секция»). Пока набор не сохранён, поля такие же, как до настройки.
У инфоблока с видимостью «Только свои» (Личные данные в инфоблоке) количество и элементы секций недоступны.
Кеш секций
Структура секций кешируется слоем «Секции и количество» (Настройки модуля -> «Кеширование», у инфоблока можно задать свой срок на табе «Кеш»); тег iblock_id_{ID} сбрасывается при изменении секции или элемента. Подробнее — Кеш.
Что почитать после секций
- Умный фильтр: фильтр, цены и количество в разделе
- Состав ответа: наборы «Секция» и «Секции»
- Инфоблок: общий обзор методов