Руководство по интеграции — msearch RAPI

Быстрый старт

RAPI — REST-эндпоинт для интеграции умного поиска в ваш сайт или приложение.

Базовый URL: https://api3.msearch.space/simpleapi/v3/rapi

Метод: GET

Формат ответа: JSON

Минимальный запрос:

GET https://api3.msearch.space/simpleapi/v3/rapi?clid=ВАШ_ДОМЕН&req=запрос

Параметры запроса

Параметр	Тип	Обязательный	Описание
`clid`	string	да	Ваш идентификатор — домен магазина. Пример: `myshop.ru`
`req`	string	да	Поисковый запрос пользователя
`page`	int	нет	Номер страницы. По умолчанию: `1`
`pageSize`	int	нет	Кол-во товаров на странице. По умолчанию: `10`
`cat`	string	нет	Фильтр по категории (см. ниже)
`priceRange`	string	нет	Диапазон цен в формате `MIN\\|MAX`. Пример: `1000\\|5000`
`available`	int	нет	`1` — только товары в наличии. По умолчанию: `0` (все товары)
`sort`	string	нет	Поле сортировки. Пример: `price`
`order`	string	нет	Направление: `ASC` или `DESC`

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

Простой поиск:

GET /simpleapi/v3/rapi?clid=myshop.ru&req=кроссовки

Поиск с пагинацией:

GET /simpleapi/v3/rapi?clid=myshop.ru&req=кроссовки&page=2&pageSize=20

Фильтр по цене:

GET /simpleapi/v3/rapi?clid=myshop.ru&req=кроссовки&priceRange=1000|9000

Только товары в наличии:

GET /simpleapi/v3/rapi?clid=myshop.ru&req=кроссовки&available=1

Фильтр по категории:

GET /simpleapi/v3/rapi?clid=myshop.ru&req=кроссовки&cat=42

Несколько категорий одновременно:

GET /simpleapi/v3/rapi?clid=myshop.ru&req=кроссовки&cat=42,87,120

Сортировка по цене (сначала дешевле):

GET /simpleapi/v3/rapi?clid=myshop.ru&req=кроссовки&sort=price&order=ASC

Комбинированный запрос:

GET /simpleapi/v3/rapi?clid=myshop.ru&req=кроссовки&page=1&pageSize=12&priceRange=2000|8000&available=1&sort=price&order=ASC

Структура ответа

{
  "categories": {...},
  "offers": [...],
  "extraOffers": null,
  "ads": [],
  "query": null,
  "suggestions": null,
  "popularData": {...},
  "pageSize": 10,
  "page": 1,
  "hits": 87,
  "nearbod_words": [...],
  "filter_data": {...},
  "order": {...},
  "t": "0.0421"
}

`offers` — список товаров

Каждый товар содержит следующие поля:

Поле	Тип	Описание
`id`	string	Уникальный ID товара
`name`	string	Название товара
`price`	float	Текущая цена
`oldPrice`	float	Старая цена (для отображения скидки), `0` если скидки нет
`available`	int	Наличие: `1` — в наличии, `0` — нет
`count`	int\|null	Количество на складе
`url`	string	Ссылка на страницу товара
`pictures`	array	Массив URL изображений (кешированные)
`pictures_original`	array	Массив URL оригинальных изображений
`snippet`	string\|null	Краткое описание / сниппет
`offerCode`	string\|null	Артикул товара
`vendor_offer`	string\|null	Бренд / производитель
`categories`	array	Массив категорий товара (обычно один элемент)
`category`	object	Категория товара (первый элемент из `categories`)

Пример товара:

{
  "id": "99852",
  "name": "Кроссовки Nike Air Max 270",
  "price": 7990,
  "oldPrice": null,
  "available": 1,
  "count": null,
  "url": "https://myshop.ru/product/99852",
  "pictures": ["https://i3.msearch.space/cache/.../img.jpg"],
  "pictures_original": ["https://myshop.ru/images/99852.jpg"],
  "snippet": null,
  "offerCode": "NK-AM270-42",
  "vendor_offer": "Nike",
  "categories": [
    {
      "id": 42,
      "parent": 5,
      "name": "Кроссовки",
      "url": "https://myshop.ru/category/krossovki"
    }
  ],
  "category": {
    "id": 42,
    "parent": 5,
    "name": "Кроссовки",
    "url": "https://myshop.ru/category/krossovki"
  }
}

`categories` — категории с результатами

Объект, где ключ — ID категории. Используется для отображения фильтра категорий.

"categories": {
  "42": { "hits": 34, "id": 42, "name": "Кроссовки" },
  "87": { "hits": 12, "id": 87, "name": "Беговые кроссовки" }
}

Поле	Описание
`id`	ID категории
`name`	Название категории
`hits`	Кол-во товаров в этой категории по запросу

Чтобы отфильтровать результаты по категории — передайте её id в параметре cat следующего запроса.

`filter_data` — данные для фильтров

"filter_data": {
  "available": 0,
  "priceRangeOut": {
    "min": 990,
    "max": 24990,
    "selected_min": 1000,
    "selected_max": 5000
  }
}

Поле	Описание
`available`	Текущий статус фильтра наличия (`0` или `1`)
`priceRangeOut.min`	Минимальная цена среди всех результатов
`priceRangeOut.max`	Максимальная цена среди всех результатов
`priceRangeOut.selected_min`	Выбранная нижняя граница (из `priceRange`), `0` если не задана
`priceRangeOut.selected_max`	Выбранная верхняя граница (из `priceRange`), `0` если не задана

min и max используются для отображения ползунка цен. selected_min / selected_max — для отображения текущего выбора пользователя.

`order` — сортировка

"order": {
  "variants": {
    "-": {
      "field": "",
      "variant": "",
      "label": "По релевантности",
      "sort": "1",
      "is_default": "1"
    },
    "price-ASC": {
      "field": "price",
      "variant": "ASC",
      "label": "Сначала дешевые",
      "sort": "2",
      "is_default": "0"
    },
    "price-DESC": {
      "field": "price",
      "variant": "DESC",
      "label": "Сначала дорогие",
      "sort": "3",
      "is_default": "0"
    }
  },
  "selectedItem": {
    "field": "",
    "variant": "",
    "label": "По релевантности",
    "sort": "1",
    "is_default": "1"
  }
}

variants — объект с вариантами сортировки (настраивается индивидуально для каждого клиента). Для применения сортировки используйте значения field и variant нужного варианта как параметры sort и order в запросе. selectedItem — текущий активный вариант (объект, аналогичный элементу variants).

`nearbod_words` — поисковые подсказки

Массив слов, близких к запросу. Можно использовать для блока «Возможно, вы искали». Возвращается только если запрос непустой и найдены результаты, иначе [].

"nearbod_words": ["кроссовок", "кроссовочки", "кеды"]

`popularData` — популярные / акционные товары

Присутствует всегда. Содержит товары для отображения при пустом запросе (акции, хиты) или дополнительные популярные результаты рядом с поиском.

"popularData": {
  "popularData": {
    "products": [...]
  }
}

Товары в popularData.popularData.products имеют идентичный формат с offers — те же поля, те же типы. Можно рендерить одним и тем же компонентом.

{
  "offerCode": "SKU-001",
  "vendor_offer": "Nike",
  "id": "1576",
  "score": null,
  "name": "Афганский казан двухцветный с ручками - 5 литров",
  "snippet": null,
  "url": "https://myshop.ru/product/1576",
  "count": 0,
  "price": 3040,
  "oldPrice": 0,
  "available": 1,
  "pictures": ["https://cdn.msearch.space/.../img.jpg"],
  "pictures_original": ["https://myshop.ru/images/img.jpg"],
  "categories": [{"id": 92, "parent": 0, "name": "Казаны", "url": "https://myshop.ru/category/kazany"}],
  "category": {"id": 92, "parent": 0, "name": "Казаны", "url": "https://myshop.ru/category/kazany"}
}

Если кешированное изображение недоступно — pictures и pictures_original будут содержать одинаковый URL оригинала.

`hits`, `page`, `pageSize` — пагинация

Поле	Описание
`hits`	Общее кол-во найденных товаров
`page`	Текущая страница
`pageSize`	Кол-во товаров на странице

Кол-во страниц: ceil(hits / pageSize)

Пагинация — пример

Первый запрос:

GET /simpleapi/v3/rapi?clid=myshop.ru&req=кроссовки&page=1&pageSize=12

Ответ: hits = 87, pageSize = 12 → всего страниц: ceil(87 / 12) = 8

Следующая страница:

GET /simpleapi/v3/rapi?clid=myshop.ru&req=кроссовки&page=2&pageSize=12

Типичный сценарий интеграции

Пользователь вводит запрос → отправляете GET /v3/rapi?clid=...&req=...
Отображаете offers — список товаров
Отображаете categories — список категорий для фильтрации
Строите ползунок цен на основе filter_data.priceRangeOut.min / max
Пользователь выбирает категорию → повторяете запрос с cat=ID
Пользователь двигает ползунок → повторяете запрос с priceRange=MIN|MAX
Пользователь меняет страницу → повторяете запрос с page=N
Пользователь меняет сортировку → повторяете запрос с sort=...&order=...

Коды ошибок

Ситуация	Поведение
Не передан `clid`	Нет ответа (соединение обрывается)
Не передан `req`	Нет ответа (соединение обрывается)
Клиент не найден / не активен	Нет ответа (соединение обрывается)
Ничего не найдено	Ответ с пустым `offers: []` и `hits: 0`

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

Для сбора аналитики по поведению пользователей отправляйте события на отдельный эндпоинт:

GET https://api3.msearch.space/simpleapi/v3/tracking

Параметр	Описание
`c`	Код клиента (ваш домен)
`e`	Тип события: `search` — поиск, `click` — клик по товару, `go` — переход
`r`	Поисковый запрос
`rc`	Кол-во результатов
`item_id`	ID товара или категории
`uid`	Уникальный ID пользователя (GUID сессии)
`gourl`	URL страницы, на которую перешёл пользователь

Пример — фиксация поиска:

GET /simpleapi/v3/tracking?c=myshop.ru&e=search&r=кроссовки&rc=87&uid=abc-123

Пример — фиксация клика по товару:

GET /simpleapi/v3/tracking?c=myshop.ru&e=click&r=кроссовки&item_id=99852&uid=abc-123&gourl=https://myshop.ru/product/99852

Ответ не возвращается. Запрос отправляется «в фоне» (fire and forget).

Руководство по интеграции — msearch RAPI

Быстрый старт

Параметры запроса

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

Структура ответа

offers — список товаров

categories — категории с результатами

filter_data — данные для фильтров

order — сортировка

nearbod_words — поисковые подсказки

popularData — популярные / акционные товары

hits, page, pageSize — пагинация