Розумний пошук Elbuz віддає ті самі результати, що й віджет, через REST API: власна сторінка пошуку чи мобільний застосунок отримують товари, категорії, фільтри й підказки за ключем вашого сайту.
Коли це знадобиться:
- Потрібна своя сторінка пошуку замість віджета — маршрут пошуку повертає товари й категорії.
- На сторінці треба показати бренди й діапазон цін — параметр
facetsдодає їх до відповіді. - Код сайту має відкрити вікно пошуку з готовим запитом — це робить об'єкт
window.SmartSearch. - Кліки з власного інтерфейсу мають потрапити в аналітику — для цього є маршрут подій.
З чого почати: візьміть адресу й ключ у блоці «API» картки віджета.
Що вміє API пошуку
- Шукає за ключем сайту — 100 запитів на хвилину, відповідь у JSON.
- Віддає товари, категорії, підказки й популярне — і приймає події для аналітики.
- Додає блоки на вимогу — бренди, наявність, атрибути, діапазон цін.
- Керує вікном пошуку — відкриває його, підставляє запит, читає кошик покупця.
Де це і хто має доступ
- Меню
- Довідники → Категорії → плитка «Налаштування віджету - Розумний пошук», вкладка «Налаштування», блок «API»
- Право доступу
- вікно «Віджет розумного пошуку товарів» у «Правах груп»
- Підготувати
- увімкнений розумний пошук і побудований пошуковий індекс
Як підключитися до API
Якщо потрібен не готовий віджет, а власна сторінка пошуку чи мобільний застосунок, той самий сервіс має REST API. Адреса й ключ показані в картці віджета, у блоці API.
| Параметр | Значення |
|---|---|
| Базова адреса | https://widget-ess.elbuz.com/api/v1 |
| Автентифікація | заголовок X-Api-Key зі значенням ключа вашого сайту (це UUID акаунта) |
| Метод | GET для читання, POST для подій |
| Обмеження | 100 запитів на хвилину на ключ; залишок видно в заголовках X-RateLimit-Remaining і X-RateLimit-Reset |
| Формат | JSON: success, data, meta.execution_time_ms; помилка — success: false і код |
Які маршрути є в API
| Маршрут | Навіщо |
|---|---|
GET /products/search | пошук товарів: q, limit, page, sort, category_id, filters, lang |
GET /suggest | легке автодоповнення для рядка пошуку |
GET /products/{id} | картка товару з відгуками |
GET /products?ids=1,2,3 | кілька товарів за списком ідентифікаторів |
GET /categories, /categories/{id}, /categories/{id}/filters | дерево категорій і доступні фільтри |
GET /popular/queries, /popular/products, /popular/categories | популярне за період |
POST /events | надіслати подію в аналітику: клік, додавання в кошик |
Як отримати бренди, наявність і фільтри
За замовчуванням пошук повертає тільки товари й категорії — це найшвидший варіант. Додаткові блоки підключаються параметром facets через кому:
brands— бренди з кількістю товарів;stock— статуси наявності з кількістю;attributes— фільтри за характеристиками;price_range— мінімальна й максимальна ціна.
Кожен FACET додає час до відповіді, тому просять тільки те, що справді показують на сторінці.
curl -H "X-Api-Key: КЛЮЧ_ВАШОГО_САЙТУ" \
"https://widget-ess.elbuz.com/api/v1/products/search?q=asus&limit=20&facets=brands,price_range&lang=uk"У відповіді два різні числа: products_count — скільки товарів у цій відповіді (з урахуванням limit), total_found — скільки знайдено всього в базі. Для пагінації беруть друге, для перевірки «чи щось прийшло» — перше. Плутанина між ними — найчастіша помилка інтеграції.
Сортування задається двома способами: префіксом (price — за зростанням, -price — за спаданням) або суфіксом (price_asc, price_desc). Без параметра sort товари ранжуються за релевантністю з урахуванням наявності.
Як керувати вікном пошуку з коду сайту
На сторінці з віджетом доступний об'єкт window.SmartSearch: через нього код вашого сайту відкриває пошук, підставляє запит і читає списки покупця.
| Метод | Що робить |
|---|---|
SmartSearch.search('запит') | шукає й відкриває вікно з результатами |
SmartSearch.setQuery('запит', true, {фільтри}) | підставляє запит і фільтри в рядок; true — одразу шукати |
SmartSearch.openWidget(), closeWidget(), isWidgetOpen() | відкрити чи закрити вікно, перевірити, чи воно відкрите |
SmartSearch.openCategoryProducts({...}) | показати товари категорії у вікні пошуку |
SmartSearch.clearFilters(), getSelectedFilters() | скинути чи прочитати фільтри покупця |
SmartSearch.getCart(), getWishlist(), getCompare(), onShoppingDataChange(fn) | кошик, обране й порівняння покупця та підписка на їх зміни |
Що робити, коли API відповідає помилкою
| Що ви бачите | Чому так | Що зробити |
|---|---|---|
| API відповідає 401 | немає заголовка X-Api-Key або ключ не той | узяти ключ із блоку API в картці віджета |
| API відповідає 429 | перевищено 100 запитів на хвилину | дочекатися скидання вікна, дивитися X-RateLimit-Reset |
У відповіді менше товарів, ніж total_found | так і має бути: це загальна кількість збігів, а не розмір сторінки | гортати сторінки параметром page |
Часті запитання
Де взяти ключ для API?
У картці віджета, у блоці «API»: там показані адреса сервісу й ключ вашого сайту. Ключ передається заголовком X-Api-Key, обмеження — сто запитів на хвилину.
Чому пошук через API повертає товари без брендів і фільтрів?
Бо за замовчуванням віддається тільки базовий шар — товари й категорії. Бренди, наявність, фільтри за характеристиками й діапазон цін підключаються параметром facets; кожен із них додає час до відповіді.
Скільки запитів можна робити до API?
100 на хвилину на ключ. Скільки лишилося, видно в заголовках X-RateLimit-Remaining і X-RateLimit-Reset; після перевищення API відповідає 429.
Як відсортувати результати за ціною?
Параметром sort: price — за зростанням, -price — за спаданням, або price_asc / price_desc. Без sort товари ранжуються за релевантністю з урахуванням наявності.
Як дізнатися, скільки всього знайдено товарів?
Беріть total_found — це всі збіги в базі. products_count — лише товари в цій відповіді з урахуванням limit.
Суміжні теми
- Якщо потрібна загальна картина — розумний пошук на сайті: що він уміє і з чого почати.
- Якщо досить готового вікна пошуку — як підключити віджет до сайту.
- Якщо потрібен обмін даними акаунта, а не пошук, — API Elbuz.