Analytics API

Analytics API принимает события поисковой аналитики: клики по товарам, добавления в корзину и покупки. Стандартный виджет Relavio Search автоматически отправляет событие click при клике по карточке товара.

Endpoint

POST /api/v1/search/events

Запрос требует API-ключ магазина.

Accept: application/json
Content-Type: application/json
api-key: YOUR_API_KEY

Типы событий

Поддерживаются типы:

Тип	Когда отправлять
click	Пользователь кликнул по товару в поиске, подсказках или каталоге.
add_to_cart	Пользователь добавил товар в корзину после поиска.
purchase	Пользователь купил товар после поиска.

Виджет автоматически отправляет только click. События add_to_cart и purchase можно отправлять из кода сайта вручную.

Тело запроса

{
  "event_id": "event-123",
  "event_type": "click",
  "search_id": "search-123",
  "session_id": "session-123",
  "product_id": "123",
  "external_id": "iphone-15-128",
  "sku": "IPHONE-15-128-BLACK",
  "product_name": "iPhone 15 128GB Black",
  "position": 1,
  "page": 1,
  "price": 99990,
  "currency": "RUB",
  "quantity": 1,
  "revenue": 99990,
  "order_id": "order-123",
  "cart_id": "cart-123",
  "occurred_at": "2026-08-02T12:00:00Z",
  "metadata": {
    "list": "catalog",
    "url": "https://example.com/products/iphone-15-128"
  }
}

Параметры

Поле	Тип	Обязательность	Описание
event_id	string	Нет	Внешний ID события. При повторной отправке с тем же event_id событие обновляется.
event_type	string	Да	Тип события: click, add_to_cart, purchase.
search_id	string	Нет	ID поиска или автодополнения. Может быть взят из cookie.
session_id	string	Нет	ID поисковой сессии. Может быть взят из cookie.
product_id	string	Нет	Внутренний числовой ID товара, если есть.
external_id	string	Нет	Внешний ID товара из каталога.
sku	string	Нет	SKU товара.
product_name	string	Нет	Название товара.
position	integer	Нет	Позиция товара в выдаче. Минимум 1.
page	integer	Нет	Страница выдачи. Минимум 1.
price	number	Нет	Цена единицы товара. Минимум 0.
currency	string	Нет	Валюта из 3 символов, например RUB.
quantity	integer	Нет	Количество. Минимум 1.
revenue	number	Нет	Выручка по событию. Если не передана для purchase, API рассчитает price * quantity.
order_id	string	Нет	ID заказа.
cart_id	string	Нет	ID корзины.
occurred_at	date	Нет	Время события. Если не передать, будет использовано текущее время сервера.
metadata	object	Нет	Дополнительные данные события.

Ответ

{
  "data": {
    "id": 1001,
    "event_id": "event-123",
    "event_type": "click"
  },
  "error": {
    "code": 0,
    "message": ""
  }
}

Как виджет отправляет click

При клике по карточке товара виджет формирует payload автоматически:

{
  "event_id": "click-1720000000000-abcd1234",
  "event_type": "click",
  "search_id": "search-123",
  "session_id": "session-123",
  "external_id": "iphone-15-128",
  "product_name": "iPhone 15 128GB Black",
  "position": 1,
  "page": 1,
  "price": 99990,
  "currency": "RUB",
  "metadata": {
    "list": "catalog",
    "url": "https://example.com/products/iphone-15-128"
  }
}

metadata.list показывает источник клика:

• search - быстрые результаты поиска;
• suggests - товары в подсказках;
• catalog - каталожная сетка.

Запрос отправляется с keepalive: true, поэтому переход по ссылке товара не блокирует отправку события.

Cookie и приоритет значений

Для search_id и session_id API сначала смотрит cookie. Если cookie нет, используются значения из payload.

Это важно для браузерной интеграции: если виджет получил cookie после поиска, события можно отправлять без явной передачи search_id и session_id, но лучше передавать их явно при серверной или кастомной интеграции.

Идемпотентность по event_id

Если передать event_id, API обновит существующее событие с таким event_id в рамках магазина или создаст новое, если его еще нет.

Это полезно при повторных отправках из-за сетевых ошибок.

Пример add_to_cart

fetch('/api/v1/search/events', {
    method: 'POST',
    credentials: 'include',
    headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
        'api-key': 'YOUR_API_KEY',
    },
    body: JSON.stringify({
        event_id: crypto.randomUUID(),
        event_type: 'add_to_cart',
        search_id: 'search-123',
        session_id: 'session-123',
        external_id: 'iphone-15-128',
        product_name: 'iPhone 15 128GB Black',
        price: 99990,
        currency: 'RUB',
        quantity: 1,
        cart_id: 'cart-123',
    }),
});

Пример purchase

fetch('/api/v1/search/events', {
    method: 'POST',
    credentials: 'include',
    headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
        'api-key': 'YOUR_API_KEY',
    },
    body: JSON.stringify({
        event_id: crypto.randomUUID(),
        event_type: 'purchase',
        search_id: 'search-123',
        session_id: 'session-123',
        external_id: 'iphone-15-128',
        product_name: 'iPhone 15 128GB Black',
        price: 99990,
        currency: 'RUB',
        quantity: 2,
        order_id: 'order-123',
    }),
});

Если revenue не передать для purchase, API рассчитает его как price * quantity.

Ошибки

401 Unauthorized

API-ключ отсутствует или неверный.

422 Validation Error

Некорректный payload. Например отсутствует event_type, передан неизвестный тип события или currency не состоит из 3 символов.