↑↓ wybierzEnter otwórzEsc zamknij

    1. Elbuz

    API inteligentnej wyszukiwarki: jak pobrać wyniki do własnej strony lub aplikacji

    2 min czytaniaZaktualizowano

    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 facets dodaje 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

    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.

    ParametrWartość
    Adres bazowyhttps://widget-ess.elbuz.com/api/v1
    Uwierzytelnianienagłówek X-Api-Key z wartością klucza Twojej strony (to konta)
    MetodaGET do odczytu, POST dla zdarzeń
    Limit100 zapytań na minutę na klucz; pozostałą liczbę widać w nagłówkach X-RateLimit-Remaining i X-RateLimit-Reset
    FormatJSON: success, data, meta.execution_time_ms; błąd — success: false i kod

    Jakie ścieżki ma API

    ŚcieżkaDo czego służy
    GET /products/searchwyszukiwanie produktów: q, limit, page, sort, category_id, filters, lang
    GET /suggestlekkie autouzupełnianie dla pola wyszukiwania
    GET /products/{id}karta produktu z opiniami
    GET /products?ids=1,2,3kilka produktów według listy identyfikatorów
    GET /categories, /categories/{id}, /categories/{id}/filtersdrzewo kategorii i dostępne filtry
    GET /popular/queries, /popular/products, /popular/categoriespopularne pozycje za okres
    POST /eventswysł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.

    MetodaCo 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 widziszDlaczego tak jestCo zrobić
    API odpowiada 401brak nagłówka X-Api-Key albo niewłaściwy kluczweź klucz z bloku API w karcie widżetu
    API odpowiada 429przekroczono 100 zapytań na minutępoczekaj na reset okna, sprawdzaj X-RateLimit-Reset
    W odpowiedzi jest mniej produktów niż total_foundtak ma być: to łączna liczba trafień, a nie rozmiar stronyprzechodź 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

    Czy ten artykuł był pomocny?

    Brakuje funkcji? Napisz do nas.

    Dodamy ją za darmo, jeśli przyda się też innym.

    Jeśli potrzebujesz jej tylko ty — umówimy się osobno.

    Spis treści

    Zaproponuj usprawnienie

    Wypróbuj Elbuz za darmo