Inteligentna wyszukiwarka Elbuz zwraca przez REST API te same wyniki co widżet: własna strona wyszukiwania lub aplikacja mobilna dostaje produkty, kategorie, filtry i podpowiedzi na podstawie klucza Twojej strony.
Kiedy to się przyda:
- Potrzebujesz własnej strony wyszukiwania zamiast widżetu — ścieżka wyszukiwania zwraca produkty i kategorie.
- Na stronie trzeba pokazać marki i zakres cen — parametr
facetsdodaje je do odpowiedzi. - Kod strony ma otworzyć okno wyszukiwania z gotowym zapytaniem — robi to obiekt
window.SmartSearch. - Kliknięcia z własnego interfejsu mają trafić do analityki — służy do tego ścieżka zdarzeń.
Od czego zacząć: weź adres i klucz w bloku „API” karty widżetu.
Co potrafi API wyszukiwania
- Szuka na podstawie klucza strony — 100 zapytań na minutę, odpowiedź w .
- Zwraca produkty, kategorie, podpowiedzi i popularne pozycje — i przyjmuje zdarzenia do analityki.
- Dodaje bloki na żądanie — marki, dostępność, atrybuty, zakres cen.
- Steruje oknem wyszukiwania — otwiera je, wstawia zapytanie, odczytuje koszyk klienta.
Jak połączyć się z API
Jeśli potrzebujesz nie gotowego widżetu, lecz własnej strony wyszukiwania lub aplikacji mobilnej, ta sama usługa ma . Adres i klucz są pokazane w karcie widżetu, w bloku API.
| Parametr | Wartość |
|---|---|
| Adres bazowy | https://widget-ess.elbuz.com/api/v1 |
| Uwierzytelnianie | nagłówek X-Api-Key z wartością klucza Twojej strony (to konta) |
| Metoda | GET do odczytu, POST dla zdarzeń |
| Limit | 100 zapytań na minutę na klucz; pozostałą liczbę widać w nagłówkach X-RateLimit-Remaining i X-RateLimit-Reset |
| Format | JSON: success, data, meta.execution_time_ms; błąd — success: false i kod |
Jakie ścieżki ma API
| Ścieżka | Do czego służy |
|---|---|
GET /products/search | wyszukiwanie produktów: q, limit, page, sort, category_id, filters, lang |
GET /suggest | lekkie autouzupełnianie dla pola wyszukiwania |
GET /products/{id} | karta produktu z opiniami |
GET /products?ids=1,2,3 | kilka produktów według listy identyfikatorów |
GET /categories, /categories/{id}, /categories/{id}/filters | drzewo kategorii i dostępne filtry |
GET /popular/queries, /popular/products, /popular/categories | popularne pozycje za okres |
POST /events | wysłanie zdarzenia do analityki: kliknięcie, dodanie do koszyka |
Jak pobrać marki, dostępność i filtry
Domyślnie wyszukiwanie zwraca tylko produkty i kategorie — to najszybszy wariant. Dodatkowe bloki włącza się parametrem facets, po przecinku:
brands— marki z liczbą produktów;stock— statusy dostępności z liczbą produktów;attributes— filtry według parametrów;price_range— cena minimalna i maksymalna.
Każdy FACET wydłuża czas odpowiedzi, więc pobiera się tylko to, co naprawdę jest pokazywane na stronie.
curl -H "X-Api-Key: KLUCZ_TWOJEJ_STRONY" \
"https://widget-ess.elbuz.com/api/v1/products/search?q=asus&limit=20&facets=brands,price_range&lang=uk"
Odpowiedź zawiera dwie różne liczby: products_count — ile produktów jest w tej odpowiedzi (z uwzględnieniem limit), total_found — ile znaleziono łącznie w bazie. Do stronicowania bierze się drugą, do sprawdzenia „czy coś przyszło” — pierwszą. Mylenie ich to najczęstszy błąd integracji.
Sortowanie ustawia się na dwa sposoby: prefiksem (price — rosnąco, -price — malejąco) albo sufiksem (price_asc, price_desc). Bez parametru sort produkty są układane według trafności z uwzględnieniem dostępności.
Jak sterować oknem wyszukiwania z kodu strony
Na stronie z widżetem dostępny jest obiekt window.SmartSearch: przez niego kod Twojej strony otwiera wyszukiwarkę, wstawia zapytanie i odczytuje listy klienta.
| Metoda | Co robi |
|---|---|
SmartSearch.search('zapytanie') | wyszukuje i otwiera okno z wynikami |
SmartSearch.setQuery('zapytanie', true, {filtry}) | wstawia zapytanie i filtry do pola; true — od razu wyszukać |
SmartSearch.openWidget(), closeWidget(), isWidgetOpen() | otwiera lub zamyka okno, sprawdza, czy jest otwarte |
SmartSearch.openCategoryProducts({...}) | pokazuje produkty kategorii w oknie wyszukiwania |
SmartSearch.clearFilters(), getSelectedFilters() | czyści lub odczytuje filtry klienta |
SmartSearch.getCart(), getWishlist(), getCompare(), onShoppingDataChange(fn) | koszyk, ulubione i porównanie klienta oraz subskrypcja ich zmian |
Co zrobić, gdy API odpowiada błędem
| Co widzisz | Dlaczego tak jest | Co zrobić |
|---|---|---|
| API odpowiada 401 | brak nagłówka X-Api-Key albo niewłaściwy klucz | weź klucz z bloku API w karcie widżetu |
| API odpowiada 429 | przekroczono 100 zapytań na minutę | poczekaj na reset okna, sprawdzaj X-RateLimit-Reset |
W odpowiedzi jest mniej produktów niż total_found | tak ma być: to łączna liczba trafień, a nie rozmiar strony | przechodź między stronami parametrem page |
Najczęstsze pytania
Skąd wziąć klucz do API?
Z karty widżetu, z bloku „API”: są tam pokazane adres usługi i klucz Twojej strony. Klucz przekazuje się nagłówkiem X-Api-Key, limit — sto zapytań na minutę.
Dlaczego wyszukiwanie przez API zwraca produkty bez marek i filtrów?
Bo domyślnie zwracana jest tylko warstwa podstawowa — produkty i kategorie. Marki, dostępność, filtry według parametrów i zakres cen włącza się parametrem facets; każdy z nich wydłuża czas odpowiedzi.
Ile zapytań można wysyłać do API?
100 na minutę na klucz. Ile zostało, widać w nagłówkach X-RateLimit-Remaining i X-RateLimit-Reset; po przekroczeniu API odpowiada 429.
Jak posortować wyniki według ceny?
Parametrem sort: price — rosnąco, -price — malejąco, albo price_asc / price_desc. Bez sort produkty są układane według trafności z uwzględnieniem dostępności.
Jak sprawdzić, ile produktów znaleziono łącznie?
Bierz total_found — to wszystkie trafienia w bazie. products_count — tylko produkty w tej odpowiedzi z uwzględnieniem limit.
Gdzie to jest i kto ma dostęp
- Menu
- Słowniki → Kategorie → kafelek „Ustawienia widżetu - Inteligentne wyszukiwanie”, zakładka „Ustawienia”, blok „API”
- Uprawnienia
- okno „Widżet inteligentnej wyszukiwarki produktów” w „Uprawnieniach grup”
- Przygotuj
- włączoną inteligentną wyszukiwarkę i zbudowany indeks wyszukiwania
Powiązane tematy
- Jeśli potrzebujesz ogólnego obrazu — inteligentna wyszukiwarka na stronie: co potrafi i od czego zacząć.
- Jeśli wystarczy gotowe okno wyszukiwania — jak podłączyć widżet do strony.
- Jeśli potrzebujesz wymiany danych konta, a nie wyszukiwania, — API Elbuz.
- Jeśli wybierasz wyszukiwarkę dla swojej strony, — co to daje Twojemu sklepowi.
