Серверная интеграция
Этапы подключения
1. Базовая интеграция
Интеграция Rocket Listing требует базовой интеграции Retail Rocket, в которую входит передача товарной базы и настройка отслеживания пользовательского поведения.
Для настроек фильтров в листинге категорий необходимо настроить передачу товарных атрибутов.
Подробнее о начале интеграции с Retail Rocket можно ознакомиться в соответствующем разделе.
Тестирование запросов
Для тестирования API-запросов вы можете воспользоваться интерактивным API-тестером в документации:
2. Настройка серверного взаимодействия
Серверная интеграция Rocket Listing позволяет получать выдачу товарного листинга напрямую через API. Это подходит для случаев, когда требуется полный контроль над отображением выдачи.
- Для работы с API необходимо следовать общим принципам интеграции;
3. Интеграция API
На этом этапе происходит подключение продукта к вашей платформе через серверное API. Подробное описание процесса интеграции вы сможете найти в следующих разделах данной инструкции.
Процесс интеграции
Получение товаров листинга
Листинг на общих страницах
Для получения персонализированного списка товаров на общих страницах, таких как главная страница, пустая корзина, пустой поиск и т.д., используется метод:
GET https://listing.retailrocket.ru/catalog/v3/partners/{partnerId}/products
Параметры
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| loadSize | number | Да | Количество запрашиваемых товаров (не более 300) |
| linkName | string | Да | Название сессии посетителя (например, session), подробнее об управлении сессией Допустимы буквы английского и русского алфавита, цифры, знак "_", пробел. Имя должно быть уникальным и не должно начинаться с цифры. |
| linkValue | string | Да | Идентификатор сессии посетителя |
| stockId | string | Нет | Идентификатор склада для мультирегиональных магазинов |
| contentId | string | Нет | Идентификатор полученного контента, используется для дозапроса следующей порции контента |
Пример ответа
{
"contentId": "61010bd1-4ed1-4fac-9699-3b8ea39d5f00",
"products": [
{
"longProductId": 12345,
"stringProductId": null
},
{
"longProductId": null,
"stringProductId": "SKU-67890"
}
]
}
В зависимости от типа идентификаторов товаров в вашей товарной базе, в ответе будет заполнено поле longProductId (для числовых ID) или stringProductId (для строковых ID). Второе поле будет null.
Листинг на странице категории
Для получения списка товаров на странице категории с поддержкой фильтров и сортировок используется метод:
POST https://listing.retailrocket.ru/category/v2/partners/{partnerId}/products
Параметры
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| categoryId | integer | Да* | Идентификатор категории (для интеграции через XML-файл) |
| categoryPath | string | Да* | Путь категории (для интеграции через Product API) |
| loadSize | number | Нет | Количество товаров при бесконечной прокрутке |
| pageSize | number | Нет | Количество товаров на странице (для классической пагинации) |
| page | number | Нет | Номер запрашиваемой страницы (используется вместе с pageSize) |
| linkName | string | Да | Название сессии посетителя, подробнее об управлении сессией Допустимы буквы английского и русского алфавита, цифры, знак "_", пробел. Имя должно быть уникальным и не должно начинаться с цифры. |
| linkValue | string | Да | Идентификатор сессии посетителя, подробнее об управлении сессией |
| stockId | string | Нет | Идентификатор склада для мультирегиональных магазинов |
| sorting | string | Нет | Вариант сортировки (relevance, popularity) |
| contentId | string | Нет | Идентификатор полученного контента, используется для дозапроса контента (см. раздел Пагинация) |
- relevance (По релевантности) — сортировка с учётом персональных рекомендаций, адаптированная под предпочтения пользователя.
- popularity (По популярности) — сортировка по общей популярности товаров в магазине, без учёта персональных предпочтений.
*Необходимо указать categoryId или categoryPath.
Тело запроса
{
"filters": []
}
При первом запросе передаётся пустой массив фильтров. Подробнее о работе с фильтрами описано в следующем разделе.
Пример ответа
{
"contentId": "61010bd1-4ed1-4fac-9699-3b8ea39d5f00",
"products": [
{
"longProductId": 12345,
"stringProductId": null
},
{
"longProductId": 67890,
"stringProductId": null
}
],
"filters": [
{
"filterId": "brand",
"title": "Бренд",
"filterType": "checkBoxFilter",
"values": [
{
"valueId": "samsung",
"valueName": "Samsung",
"count": 42
},
{
"valueId": "apple",
"valueName": "Apple",
"count": 38
}
]
},
{
"filterId": "price",
"title": "Цена",
"filterType": "intervalFilter",
"minValue": 1000,
"maxValue": 150000
}
],
"sortings": [
{
"sortingId": "relevance",
"sortingName": "По релевантности"
},
{
"sortingId": "popularity",
"sortingName": "По популярности"
}
],
"selectedSortingId": "relevance"
}
Работа с фильтрами
Запрос без выбранных фильтров
При первой загрузке страницы категории передаётся пустой массив фильтров:
{
"filters": []
}
В ответе API возвращает все доступные фильтры с их значениями и списком сортировок. Это позволяет отобразить пользователю полный набор инструментов для фильтрации.
Форматы значений фильтров в запросе
При выборе пользователем значений фильтров необходимо передавать их в соответствующем формате.
Радиокнопка (radioButtonFilterValue)
Выбор одного значения из списка:
{
"filters": [
{
"filterId": "brand",
"selectedValueIds": ["samsung"]
}
]
}
Чекбокс (checkBoxFilterValue)
Выбор нескольких значений из списка:
{
"filters": [
{
"filterId": "color",
"selectedValueIds": ["red", "blue", "green"]
}
]
}
Интервал (intervalFilterValue)
Выбор диапазона значений:
{
"filters": [
{
"filterId": "price",
"selectedMin": 5000,
"selectedMax": 50000
}
]
}
Комбинированный запрос
Можно передавать несколько фильтров одновременно:
{
"filters": [
{
"filterId": "brand",
"selectedValueIds": ["samsung", "apple"]
},
{
"filterId": "price",
"selectedMin": 10000,
"selectedMax": 80000
},
{
"filterId": "color",
"selectedValueIds": ["black"]
}
]
}
Форматы фильтров в ответе
В ответе API возвращает фильтры с информацией о выбранных значениях.
Радиокнопка (radioButtonFilter)
{
"filterId": "gender",
"title": "Пол",
"filterType": "radioButtonFilter",
"selectedValueId": "male",
"values": [
{
"valueId": "male",
"valueName": "Мужской",
"count": 150
},
{
"valueId": "female",
"valueName": "Женский",
"count": 200
}
]
}
Чекбокс (checkBoxFilter)
{
"filterId": "brand",
"title": "Бренд",
"filterType": "checkBoxFilter",
"values": [
{
"valueId": "samsung",
"valueName": "Samsung",
"count": 42,
"isSelected": true
},
{
"valueId": "apple",
"valueName": "Apple",
"count": 38,
"isSelected": false
}
]
}
Интервал (intervalFilter)
{
"filterId": "price",
"title": "Цена",
"filterType": "intervalFilter",
"minValue": 1000,
"maxValue": 150000,
"selectedMin": 5000,
"selectedMax": 50000
}
Пагинация
Пагинация поддерживается только для листинга на странице категории (POST /category/v2/partners/{partnerId}/products). Для листинга на общих страницах (GET /catalog/v3/...) пагинация недоступна.
Rocket Listing поддерживает два режима загрузки товаров.
Бесконечная прокрутка
Используется параметр loadSize для указания количества товаров в каждой порции:
?loadSize=20
При подгрузке следующей порции передаётся contentId из предыдущего ответа:
?loadSize=20&contentId=61010bd1-4ed1-4fac-9699-3b8ea39d5f00
Классическая пагинация
Используются параметры pageSize и page:
?pageSize=20&page=1
Для перехода на следующую страницу:
?pageSize=20&page=2&contentId=61010bd1-4ed1-4fac-9699-3b8ea39d5f00
Параметр contentId фиксирует выдачу, обеспечивая последовательную дозагрузку результатов. Он используется только при подгрузке следующих порций товаров — значение берётся из ответа предыдущего запроса.
Передача данных о взаимодействии с листингом
Для корректной работы персонализации и аналитики необходимо передавать события взаимодействия пользователей с листингом.
Подробнее о методах можно узнать в разделе Взаимодействие с рекомендациями.