OpenCart Autocomplete API: миттєві пошук-підказки на сайт

Стандартний OpenCart-пошук має базовий autocomplete-механізм, але він обмежений LIKE-поведінкою (без морфології, опечаток, синонімів) і не масштабується на 10k+ SKU. AI Search надає повноцінний REST API для autocomplete-suggestions, який підключається у будь-яку OpenCart-тему 1-2 рядками JavaScript. У цій статті — повний технічний гайд для розробників.

Що таке autocomplete і навіщо він магазину

Autocomplete (миттєві підказки під час набору) — фіча яка скорочує час до товару у 2-4 рази:

На mobile autocomplete особливо критичний — друкувати на маленькій клавіатурі повільно. Якщо після 3-4 літер користувач бачить релевантні підказки і кликає — це перемога UX.

REST endpoint AI Search Autocomplete API

POST https://api.ai-search.cc/v1/autocomplete

Автентифікація: X-API-Key header (отримати у кабінеті ai-search.cc → Settings → API Keys).

Повна специфікація API з усіма endpoints (search, autocomplete, indexing, analytics) — у Documentation.

Формат запиту

POST /v1/autocomplete HTTP/1.1
Host: api.ai-search.cc
Content-Type: application/json
X-API-Key: VMILJRPH-G1T5F7PM-IO4MMSUD

{
  "q": "чашк",
  "store_id": 0,
  "language_id": 1,
  "limit": 10,
  "include": ["products", "categories", "queries"]
}

Формат відповіді

HTTP/1.1 200 OK
Content-Type: application/json

{
  "took_ms": 47,
  "suggestions": {
    "products": [
      {
        "id": 1234,
        "name": "Чашка кавова керамічна 250мл",
        "url": "https://shop.com/index.php?route=product/product&product_id=1234",
        "image": "https://shop.com/image/cache/catalog/products/1234-100x100.jpg",
        "price": "199.00",
        "score": 0.94
      }
    ],
    "categories": [
      {"id": 67, "name": "Чашки і кружки", "url": "...", "products_count": 47}
    ],
    "queries": [
      "чашка кавова",
      "чашка з блюдцем",
      "чашка термос"
    ]
  }
}

Інтеграція JavaScript

Vanilla JS (без залежностей)

const input = document.querySelector('#search-input');
const suggestionsBox = document.querySelector('#suggestions');

let debounceTimer;
input.addEventListener('input', (e) => {
  clearTimeout(debounceTimer);
  const q = e.target.value.trim();
  if (q.length < 2) { suggestionsBox.innerHTML = ''; return; }

  debounceTimer = setTimeout(async () => {
    const res = await fetch('/index.php?route=extension/aisearch/api/autocomplete&q=' + encodeURIComponent(q));
    const data = await res.json();

    suggestionsBox.innerHTML = data.suggestions.products.map(p => `
      <a href="${p.url}" class="suggestion">
        <img src="${p.image}" alt="">
        <span class="name">${p.name}</span>
        <span class="price">${p.price}</span>
      </a>
    `).join('');
  }, 200); // 200ms debounce
});

jQuery (для legacy-тем)

$('#search-input').on('input', _.debounce(function() {
  const q = $(this).val().trim();
  if (q.length < 2) { $('#suggestions').empty(); return; }

  $.getJSON('/index.php?route=extension/aisearch/api/autocomplete', {q: q}, function(data) {
    const html = data.suggestions.products.map(p => `
      <a href="${p.url}">${p.name} - ${p.price}</a>
    `).join('');
    $('#suggestions').html(html);
  });
}, 200));

Інтеграція з PHP-бекенду

Створіть catalog/controller/extension/aisearch/api.php у вашому OpenCart, який служить як proxy:

<?php
class ControllerExtensionAisearchApi extends Controller {
    public function autocomplete() {
        $q = $this->request->get['q'] ?? '';
        if (mb_strlen($q) < 2) {
            return $this->response->setOutput(json_encode(['suggestions' => []]));
        }

        $payload = [
            'q' => $q,
            'store_id' => (int)$this->config->get('config_store_id'),
            'language_id' => (int)$this->config->get('config_language_id'),
            'limit' => 10,
            'include' => ['products', 'categories', 'queries']
        ];

        $ch = curl_init('https://api.ai-search.cc/v1/autocomplete');
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'X-API-Key: ' . $this->config->get('aisearch_api_key')
        ]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 5);

        $response = curl_exec($ch);
        curl_close($ch);

        $this->response->addHeader('Content-Type: application/json');
        $this->response->setOutput($response);
    }
}

CORS і безпека

API сервер встановлює дозволені origin-и через ваш domain-allowlist у кабінеті:

• За замовчуванням дозволено лише origin вашого магазину (з license-domain)
• У Settings → CORS Origins можна додати дев-домени, mobile-apps, marketplace-redirects
• Всі запити з невідомих origin-ів отримують 403 Forbidden

Rate-limits

При перевищенні — HTTP 429 Too Many Requests з заголовком Retry-After: NN (секунди до наступного слоту).

Кастомізація вигляду suggestions

JSON-відповідь — лише дані. UI повністю на вашій стороні. Базові підходи:

1. Dropdown під input-полем — стандартний UX, працює скрізь.
2. Full-screen overlay на mobile — як у Amazon/Aliexpress.
3. Сторінкові hint-секції — "Популярні запити", "Категорії", "Товари" в окремих колонках.
4. Multi-column desktop — товари в одній колонці, категорії в іншій.

FAQ

Чи API працює без основного модуля AI Search?

Ні. API будується на тих самих embeddings які індексуються через основний модуль. Спочатку встановіть AI Search, потім використовуйте Autocomplete API.

Чи можна викликати API безпосередньо з frontend без proxy?

Технічно так (CORS дозволяє), але ваш API key опиниться у DevTools покупців. Завжди робіть proxy через ваш OpenCart-controller.

А якщо у мене SPA на React/Vue?

Той самий підхід: proxy-endpoint у OpenCart, frontend викликає його. Або зробіть Server-Side Rendering API gateway (наприклад через Next.js).

Чи API підтримує фільтрацію по категоріях?

Так. Параметр filter_category_ids: [1,5,12] у request body — обмежує autocomplete лише вказаними категоріями (корисно для category-page autocomplete).

Чи API працює з 100+ мовами?

Так. Усі автокомплет-запити використовують ту ж multilingual-e5-large модель, що й основний пошук — тому suggestion-и розуміють морфологію, опечатки та cross-language запити (UA→RU, EN→UA тощо). Деталі у статті «Multilingual Search для OpenCart».

Скільки часу займає типовий запит?

30-80ms на наших серверах + network latency. На EU-локаціях зазвичай 100-150ms total. Через CDN-edge-proxy (для Pro+) — 40-70ms.

Чи є SDK для популярних мов?

Поки що тільки REST API + приклади на PHP/JS. У roadmap — офіційні npm-пакет (@aisearch/sdk) і Composer (aisearch/php-sdk) на Q3 2026.