Skip to main content

Вступ

API пошуку Spefix дозволяє показувати результати миттєво, персоналізовано й синхронно з даними, які ви передаєте через імпорт. Цей розділ допоможе зрозуміти, як побудований пошук, які кроки треба виконати перед інтеграцією, та які сценарії підтримуються «з коробки».

Що таке Search API​

Search API — це ендпоінт, який повертає релевантні продукти та пов’язані категорії залежно від пошукового запиту користувача. Серед особливостей:

  • Підтримка TL;DR-запитів — можна передавати як короткі, так і довгі фрази, система працює без урахування регістру.
  • Розумна інтерпретація — пошук нормалізує запит, виправляє помилки, підказує релевантні категорії та атрибути.
  • Фільтрація — можна застосувати обмеження за ціною, категорією, доступністю, а також власними атрибутами (параметрами) з імпорту.
  • Дворівнева пагінація — результати можна отримувати як плаский список або згрупованими за категоріями.

Підготовчі кроки​

Перш ніж стукатися в Search API, переконайтеся, що виконані базові інтеграційні вимоги:

  • Синхронізовані категорії та товари. Розділи Імпорт категорій і Імпорт товарів описують, як це зробити.
  • Токен доступу. Для Search API використовується окремий token, який передається як параметр запиту (не в заголовках). Якщо ще не отримали його, зверніться до вашого менеджера або створіть в адмінці Spefix.
  • Актуальна локалізація. Усі назви, опис, атрибути залежать від мов, на які ви переклали дані в API імпорту.

Архітектура та сценарії​

  • Фронтенд відправляє запит GET /search/v2/ з пошуковою фразою.
  • API пошуку виконує повнотекстовий пошук, застосовує фільтри та повертає структуровану відповідь.
  • Інтерфейс відображає продукти, категорії, доступні фільтри та формує пагінацію.
  • Аналітика — якщо не вказати demo=true, пошук зберігає агреговану статистику для звітності (не персональні дані).

Рекомендації з інтеграції​

  • Кешуйте відповіді щонайменше на 2–5 секунд на рівні вашого фронтенда (особливо коли користувач швидко набирає запит). Це зменшить навантаження та покращить UX.
  • Передавайте uuid. Вкажіть власний ідентифікатор сеансу/користувача, щоб згодом аналізувати, як часто люди змінюють запит.
  • Контролюйте фільтри. Значення filters — це ID атрибутів, а не текст назви. Їх можна отримати з поля filters у попередній відповіді.
  • Обробляйте порожні результати. Якщо пошук нічого не знайшов, система все одно поверне JSON з total = 0. Покажіть підказки, а не «404».
  • Слідкуйте за токеном. Це публічний параметр, але генеруйте окремий токен для кожного джерела (ваш сайт, мобільний додаток, віджет партнера), щоб можна було відстежувати статистику.

Обмеження та продуктивність​

  • Час відповіді. У середньому 100–200 мс, але залежить від географії та обсягу фільтрів.
  • Ресурси. Параметри product_page_size і per_category_limit впливають на обсяг відповіді. Віддавати одночасно 100 продуктів у кожній категорії — не дуже добра ідея.
  • Частота запитів. Помірна. Якщо плануєте сотні запитів на секунду, узгодьте це з технічною підтримкою Spefix, щоб розширити ліміти.
  • Тестове середовище. Використовуйте demo=true, коли тестуєте в розробці, щоб не засмічувати аналітику.