Методы списков
| Метод | Адрес | Кто вызывает | Начинает сессию |
|---|---|---|---|
| Записи списка с карточками элементов | GET /api/list | гость и вошедший | нет |
| ID элементов списка без карточек | GET /api/list/elementID | гость и вошедший | нет |
| Добавить элемент в список | POST /api/list | гость и вошедший | да |
| Удалить записи из списка | DELETE /api/list | гость и вошедший | нет |
Название списка передаётся параметром list_name (обязателен): принято favorites (избранное), comparison (сравнение), visited (просмотренные), но подойдёт любое имя. Без list_name — 400.
Избранное и просмотренные на витрине
- Гость нажимает «В избранное»:
POST /api/listсlist_name=favoritesиelement_id. Метод начинает сессию, витрина сохраняетX-Session-Idиз заголовка ответа. - На карточках каталога кнопки «в избранном» подсвечиваются по
GET /api/list/elementID?list_name=favorites: только ID элементов, без сборки карточек — лёгкий запрос. - Страница «Избранное» вызывает
GET /api/list?list_name=favoritesи получает записи с карточками элементов. - «Убрать из избранного» —
DELETE /api/listсlist_nameиelement_id; безelement_idиcodeочищается весь список. - Просмотр карточки товара витрина записывает в список
visited.
Все запросы после первого идут с заголовком X-Session-Id, иначе гость не увидит свои записи.
Добавление
curl -i -X POST "https://example.ru/api/list" \
-H "Content-Type: application/json" \
-d '{"list_name": "favorites", "element_id": 105}' HTTP/1.1 200 OK
X-Session-Id: JLfAjGOFZ3qb2elyU2VIxlhvt1kYjQMZ {
"success": true
} Можно добавлять простые товары и предложения (для предложения в список пишется товар), а также элементы любых инфоблоков в любые списки. name — название записи (по умолчанию название элемента), data — произвольные данные записи (JSON-объект или строка), возвращаются в поле data. Повторное добавление того же элемента заменяет прежнюю запись.
Чтение
curl "https://example.ru/api/list?list_name=favorites" -H "X-Session-Id: JLfAjGOFZ3qb2elyU2VIxlhvt1kYjQMZ" {
"data": [
{
"name": "Футболка базовая",
"code": "5f1c0c1e2b7a4d3e9a8b7c6d5e4f3a2b",
"data": null,
"datetimeAdd": "2026-01-01 12:00:00",
"iblockId": 2,
"id": 105
}
],
"pagen": { "total": 1, "limit": 10, "offset": 0 }
} К полям записи добавлены поля карточки элемента по набору «Список» (Состав ответа). Для предложения возвращается товар, выбранное предложение — в selectedOfferId. Записи элементов удалённых инфоблоков отдаются без карточки. Постраничный вывод — limit (по умолчанию 10), offset, pagen. Сортировка order — JSON-объект {поле: направление}, по умолчанию {"datetimeAdd":"desc","name":"asc"}.
Для гостя без записей (или без X-Session-Id) список пуст:
{
"data": [],
"pagen": { "total": 0, "limit": 10, "offset": 0 }
} GET /api/list/elementID отдаёт {"data": [{"id": 105}], "pagen": {...}}. Сортировать можно только по name, datetimeAdd, elementId, id (направление asc или desc), иначе 400 с названием поля в тексте.
Удаление
curl -X DELETE "https://example.ru/api/list?list_name=favorites&element_id=105" -H "X-Session-Id: JLfAjGOFZ3qb2elyU2VIxlhvt1kYjQMZ" Ответ {"success": true}; он такой же и когда подходящих записей нет. Для товара с предложениями в element_id передают ID предложения; code — код записи (поле code).
Где настраиваются списки
- Состав карточки элемента в списке — набор «Список»: Настройки модуля -> вкладка «Инфоблоки» -> инфоблок -> таб «Элементы».
- Срок хранения анонимных записей «просмотренных»: вкладка «Пользователи», «Сколько дней хранить анонимные «просмотренные»». В списке
visitedхранятся последние 20 записей пользователя, анонимные записи чистит агент. - Данные списков не кешируются: это данные пользователя.
Ограничения списков
- Записи гостя привязаны к сессии: если витрина потеряла
X-Session-Id, они недоступны. - Часть ошибок приходит телом
{errors: [...]}, часть —{success: false, error: текст}: читайте текст изerrorилиerrors[0].
Что почитать после списков
- Сессия и авторизация
- Состав ответа: набор «Список»
- Быстрый старт