OpenCart Autocomplete API: мгновенные поисковые подсказки

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

Зачем autocomplete

REST endpoint

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

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

Полная спецификация API — в 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": "...", "image": "...", "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}">${p.name} - ${p.price}</a>`).join('');
  }, 200);
});

PHP backend (proxy)

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

        $ch = curl_init('https://api.ai-search.cc/v1/autocomplete');
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'q' => $q,
            'store_id' => (int)$this->config->get('config_store_id'),
            'language_id' => (int)$this->config->get('config_language_id'),
            'limit' => 10,
        ]));
        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);
        $this->response->addHeader('Content-Type: application/json');
        $this->response->setOutput(curl_exec($ch));
        curl_close($ch);
    }
}

CORS и безопасность

API сервер устанавливает разрешённые origin-ы через ваш domain-allowlist в кабинете. По умолчанию — только origin вашего магазина. CORS Origins можно добавить в Settings.

Rate-limits

Кастомизация suggestions

1. Dropdown под input — стандартный UX
2. Full-screen overlay на mobile — как у Amazon/Aliexpress
3. Hint-секции — "Популярные запросы", "Категории", "Товары"
4. Multi-column desktop

FAQ

API работает без основного модуля?

Нет. API использует те же embeddings, что и основной модуль.

Можно ли вызывать API напрямую с frontend без proxy?

Технически да, но API key окажется в DevTools. Всегда proxy через OpenCart-controller.

А если SPA на React/Vue?

Тот же подход: proxy-endpoint в OpenCart, frontend вызывает его.

Поддерживает ли API фильтрацию по категориям?

Да. Параметр filter_category_ids: [1,5,12] в request body.

Сколько занимает запрос?

30-80ms серверного времени + network. На EU: 100-150ms. Pro+ через CDN: 40-70ms.

Есть ли SDK?

Пока REST API + примеры PHP/JS. В roadmap: npm (@aisearch/sdk) и Composer Q3 2026.