Ключевые понятия
| Термин | Что это | Где взять |
|---|---|---|
Проект, uuid |
Ваш магазин в SearchBooster. UUID — публичный ключ API, передаётся в пути каждого запроса: /api/{uuid}/search. |
Личный кабинет → настройки проекта |
| Оффер | Товар из фида. id оффера — ключ во всех методах: рекомендации, события, find-by-id. |
offer@id в фиде |
Группа, groupId |
Варианты одной модели (размеры, цвета). | offer@group_id |
userId |
Стабильный ID посетителя. Связывает поиск, историю, события и рекомендации одного человека. | Cookie searchbooster_v2_user_id или ваш ID |
regionId |
Регион посетителя — выбирает цены и наличие. | <region id> в фиде |
segmentId |
Сегмент посетителя (опт, VIP) для правил мерчандайзинга. | Ваша логика |
queryId |
ID конкретного поискового ответа — связывает клик с запросом. | Генерируете сами |
searchId |
ID поисковой сессии — несколько уточнений подряд. | Генерируете сами |
client |
Платформа: desktop, mobile_ios, mobile_android, mobile_app_ios, mobile_app_android. |
— |
| Виджет | Блок рекомендаций или поисковое окно с настройками в личном кабинете. У виджета рекомендаций есть числовой ID. | Личный кабинет → Виджеты |
| Фасет | Описание фильтра в ответе поиска: доступные значения и количество товаров. | Поле params ответа /search |
| Мерчандайзинг | Правила выдачи: закрепить, поднять, скрыть, редирект, синонимы. | Личный кабинет → Мерчандайзинг |
Аутентификация
Заголовок раздела «Аутентификация»API поиска, подсказок, рекомендаций и событий публичное: ключа нет, проект определяется по UUID. Его можно вызывать прямо из браузера и мобильного приложения, CORS разрешён для любых доменов.
Методы, которые меняют данные или отдают статистику, требуют API-ключ (Authorization: Bearer …): API индексации, API статистики. Ключ выпускается в профиле личного кабинета и хранится только на сервере.
userId: правила
Заголовок раздела «userId: правила»- Сайт с трекером или виджетом: берите значение cookie
searchbooster_v2_user_id. - Свой ID (авторизованные пользователи, CRM): передайте его виджету через
sbUserId, трекеру — через настройку cookie, и используйте его во всех запросах API. - Мобильное приложение: UUID, сгенерированный при первом запуске и сохранённый на устройстве.
- Не передавайте email, телефон и другие персональные данные — только непрозрачный ID.
Формат данных
Заголовок раздела «Формат данных»- Все ответы — JSON в UTF-8.
- Параметры-объекты в GET (
params,completionSettings,imagesSize) передаются JSON-строкой; не забывайте URL-кодирование (encodeURIComponent,URLSearchParams). - ID товаров и категорий — строки, даже если выглядят как числа.
- Цены — числа в валюте фида.