Серверная интеграция

Этапы подключения

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	Нет	Идентификатор полученного контента, используется для дозапроса контента (см. раздел Пагинация)

*Необходимо указать 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
}

---

Пагинация

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 фиксирует выдачу, обеспечивая последовательную дозагрузку результатов. Он используется только при подгрузке следующих порций товаров — значение берётся из ответа предыдущего запроса.

---

Передача данных о взаимодействии с листингом

Для корректной работы персонализации и аналитики необходимо передавать события взаимодействия пользователей с листингом.

Трекинг событий

Подробнее о методах трекинга можно узнать в разделе Взаимодействие с рекомендациями.

---

Настройка фильтров

Для настройки фильтров в категорийном листинге ознакомьтесь с разделом Подготовка фильтров.

---