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

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

1. Базовая интеграция

Интеграция Rocket Search требует базовой интеграции Retail Rocket, в которую входит передача товарной базы и настройка отслеживания пользовательского поведения.

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

Базовые этапы интеграции

Подробнее о начале интеграции с Retail Rocket можно ознакомиться в соответствующем разделе.

Тестирование запросов

Для тестирования API-запросов вы можете воспользоваться интерактивным API-тестером в документации:

2. Настройка серверного взаимодействия

Серверная интеграция Rocket Search позволяет получать поисковую выдачу и предпросмотр напрямую через API. Этот вариант подходит для проектов, где требуется полный контроль над отображением поиска и обработкой пользовательских сценариев на стороне сервера.

к сведению

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

3. Интеграция API

На этом этапе происходит подключение продукта к вашей платформе через серверное API. Ниже описаны методы получения поисковых данных, работа с фильтрами и передача пользовательских событий.

Процесс интеграции

Получение поисковой выдачи

Для получения полной поисковой выдачи используется метод:

POST https://api.rocketsearch.ru/rocketsearch/v5/partner/{partnerId}/phrase/{phrase}/page/

Параметры

Параметр	Тип	Обязательный	Описание
phrase	string	Да	Поисковая фраза с использованием URL-encoding
page	number	Да	Номер страницы, начиная с 1
pageSize	number	Да	Количество товаров на странице
lang	string	Да	Язык магазина
stock	string	Нет	Идентификатор склада для мультирегиональных магазинов
sorting	string	Нет	Идентификатор выбранной сортировки
linkName	string	Да*	Название идентификатора сессии
linkValue	string	Да*	Значение идентификатора сессии

Тело запроса

При первом запросе передаётся пустой массив фильтров:

{
  "filters": []
}

Пример запроса

curl -X POST 'https://api.rocketsearch.ru/rocketsearch/v5/partner/59908d02c7d013ce40de715a/phrase/%D0%BC%D0%BE%D0%BD%D0%B8%D1%82%D0%BE%D1%80/page/?apiKey=testKey&page=1&pageSize=24&lang=ru&stock=14&linkName=session&linkValue=42' \
  -H 'Content-Type: application/json' \
  -d '{"filters": []}'

Пример ответа (товары найдены)

{
  "resultsPage": {
    "productsCount": 407,
    "pagesCount": 17,
    "contentId": "5831a77b-6747-47c5-b10b-0c8e16c1a342",
    "products": [
      {
        "productId": 1193253
      },
      {
        "productId": 1209366
      }
    ],
    "filters": [
      {
        "checkBoxFilter": {
          "filterId": "brands",
          "title": "Производитель",
          "retrievedValues": [
            {
              "valueId": "brand_0",
              "title": "brand_title_0",
              "count": 74,
              "isSelected": false
            },
            {
              "valueId": "brand_1",
              "title": "brand_title_1",
              "count": 23,
              "isSelected": false
            }
          ]
        }
      }
    ],
    "sortings": [
      {
        "sortingId": null,
        "title": "По релевантности"
      },
      {
        "sortingId": "price_asc",
        "title": "Сначала дешевые"
      }
    ],
    "selectedSortingId": null
  }
}

Пустая выдача

Если по поисковой фразе отсутствуют результаты, то ответ будет содержать объект emptyResultsPage.

{
  "emptyResultsPage": {
    "contentId": "49889283-1f23-4b18-afec-1daaa91b21aa"
  }
}

Редирект в категорию

Если поисковая фраза совпадает с наименованием этой категории, то платформа может определить, что вместо показа результатов поиска целесообразно перейти на страницу категории самого магазина.

В таком случае ответ запроса поисковой выдачи будет содержать такой объект:

{
  "categoryRedirect": {
    "contentId": "49889283-1f23-4b18-afec-1daaa91b21aa",
    "category": {
      "categoryId": 3431
    }
  }
}

подсказка

Если магазин интегрирован через Product API, вместо categoryId может использоваться categoryPath.

Работа с фильтрами и сортировками

После первого запроса вы получаете список доступных фильтров и сортировок. При повторных запросах передавайте выбранные фильтры в filters, а сортировку в query-параметре sorting.

Формат фильтров в запросе

Поддерживаются следующие типы значений фильтра:

radioButtonFilterValue

{
  "radioButtonFilterValue": {
    "filterId": "categories",
    "selectedValueId": "3883"
  }
}

checkBoxFilterValue

{
  "checkBoxFilterValue": {
    "filterId": "brands",
    "selectedValueIds": [
      "brand_0",
      "brand_1"
    ]
  }
}

intervalFilterValue

{
  "intervalFilterValue": {
    "filterId": "price",
    "selectedMin": 10000,
    "selectedMax": 100000
  }
}

ratingFilterValue

{
  "ratingFilterValue": {
    "filterId": "rating",
    "selectedValues": [
      3,
      4
    ]
  }
}

switchFilterValue

{
  "switchFilterValue": {
    "filterId": "available",
    "value": true
  }
}

Комбинированный пример `filters`

{
  "filters": [
    {
      "checkBoxFilterValue": {
        "filterId": "brands",
        "selectedValueIds": [
          "brand_0",
          "brand_1"
        ]
      }
    },
    {
      "intervalFilterValue": {
        "filterId": "price",
        "selectedMin": 10000,
        "selectedMax": 100000
      }
    },
    {
      "switchFilterValue": {
        "filterId": "available",
        "value": true
      }
    }
  ]
}

Форматы фильтров в ответе

API возвращает фильтры в виде типизированных объектов.

radioButtonFilter

{
  "radioButtonFilter": {
    "filterId": "categories",
    "title": "Категория",
    "retrievedValues": [
      {
        "valueId": "12",
        "title": "мониторы",
        "count": 404
      }
    ],
    "selectedValueId": null
  }
}

checkBoxFilter

{
  "checkBoxFilter": {
    "filterId": "brands",
    "title": "Производитель",
    "retrievedValues": [
      {
        "valueId": "brand_0",
        "title": "brand_title_0",
        "count": 74,
        "isSelected": true
      }
    ]
  }
}

intervalFilter

{
  "intervalFilter": {
    "filterId": "price",
    "title": "Цена",
    "retrievedMin": 7699,
    "retrievedMax": 224100,
    "selectedMin": 10000,
    "selectedMax": 100000
  }
}

ratingFilter

{
  "ratingFilter": {
    "filterId": "rating",
    "title": "Рейтинг",
    "retrievedValues": [
      {
        "value": 4,
        "count": 43,
        "isSelected": true
      }
    ]
  }
}

switchFilter

{
  "switchFilter": {
    "filterId": "available",
    "title": "Только в наличии",
    "value": true
  }
}

Получение предпросмотра поиска

Для получения данных предпросмотра (товары, категории, подсказки) используется метод:

GET https://api.rocketsearch.ru/rocketsearch/v5/partner/{partnerId}/phrase/{phrase}/preview/

Параметры

Параметр	Тип	Обязательный	Описание
phrase	string	Да	Поисковая фраза с использованием URL-encoding
lang	string	Да	Язык магазина
stock	string	Нет	Идентификатор склада
linkName	string	Да*	Название идентификатора сессии
linkValue	string	Да*	Значение идентификатора сессии

Пример ответа предпросмотра

{
  "contentId": "49889283-1f23-4b18-afec-1daaa91b21aa",
  "products": [
    {
      "productId": 1193253
    },
    {
      "productId": 1209366
    }
  ],
  "suggestions": [
    "системный блок",
    "системный блок игровой"
  ],
  "categories": [
    {
      "categoryId": 495
    },
    {
      "categoryId": 5986
    }
  ]
}

suggestions - массив строк-подсказок с поисковой фразой

categories - массив объектов для редиректа на категорию

Пагинация

Для пагинации в поисковой выдаче используются параметры page и pageSize:

?page=1&pageSize=24

При переходе к следующей странице:

?page=2&pageSize=24&contentId=61010bd1-4ed1-4fac-9699-3b8ea39d5f00

Важно

Параметр contentId фиксирует выдачу, обеспечивая последовательную дозагрузку результатов. Он используется только при подгрузке следующих порций товаров — значение берётся из ответа предыдущего запроса.

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

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

Трекинг событий взаимодействия

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

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

1. Базовая интеграция​

Тестирование запросов​

2. Настройка серверного взаимодействия​

3. Интеграция API​

Процесс интеграции​

Получение поисковой выдачи​

Параметры​

Тело запроса​

Пример запроса​

Пример ответа (товары найдены)​

Пустая выдача​

Редирект в категорию​

Работа с фильтрами и сортировками​

Формат фильтров в запросе​

radioButtonFilterValue​

checkBoxFilterValue​

intervalFilterValue​

ratingFilterValue​

switchFilterValue​

Комбинированный пример filters​

Форматы фильтров в ответе​

radioButtonFilter​

checkBoxFilter​

intervalFilter​

ratingFilter​

switchFilter​

Получение предпросмотра поиска​

Параметры​

Пример ответа предпросмотра​

Пагинация​

Передача данных о взаимодействии с поиском​

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

1. Базовая интеграция

Тестирование запросов

2. Настройка серверного взаимодействия

3. Интеграция API

Процесс интеграции

Получение поисковой выдачи

Параметры

Тело запроса

Пример запроса

Пример ответа (товары найдены)

Пустая выдача

Редирект в категорию

Работа с фильтрами и сортировками

Формат фильтров в запросе

radioButtonFilterValue

checkBoxFilterValue

intervalFilterValue

ratingFilterValue

switchFilterValue

Комбинированный пример `filters`

Форматы фильтров в ответе

radioButtonFilter

checkBoxFilter

intervalFilter

ratingFilter

switchFilter

Получение предпросмотра поиска

Параметры

Пример ответа предпросмотра

Пагинация

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