SwiftSearch

Dokumentacja

Jak działa SwiftSearch

Własny silnik wyszukiwania SwiftSearch indeksuje katalog produktów w pamięci, żeby wyniki wracały w kilkanaście milisekund, z tolerancją literówek, synonimami, filtrami po kategoriach/marce/atrybutach i opcjonalnym wyszukiwaniem semantycznym (AI). Poniżej krok po kroku: jak podłączyć sklep i jak wygląda publiczne API wyszukiwania.

Silnik wyszukiwania SwiftSearch

Katalog produktów trzymany jest w indeksie w pamięci, oddzielnie od bazy danych sklepu, dzięki temu wyszukiwanie nie obciąża serwera sklepu i nie zwalnia wraz z rosnącym ruchem.

Tolerancja literówek i odmian

„koszula" znajdzie też „koszule", literówka w nazwie marki czy produktu nie kończy się zerem wyników.

Dopasowanie po numerze katalogowym (SKU)

Zapytania wyglądające jak SKU są rozpoznawane i trafiają dokładnie w produkt, zamiast gubić się w wyszukiwaniu pełnotekstowym po wielu polach.

Filtry

Kategorie, marka i dowolne atrybuty własne katalogu jako gotowe checkboxy z liczbą wyników, konfigurowalne z panelu.

Wyszukiwanie semantyczne (AI)

Opcjonalnie: rozumienie znaczenia zapytania, nie tylko dopasowania słów, dostępne od planu Business, razem z sugestiami „podobne produkty".

Integracja krok po kroku

Katalog trafia do indeksu SwiftSearch przez gotową wtyczkę albo moduł, zależnie od platformy sklepu.

Publiczne API wyszukiwania

Te same dwa endpointy, które napędzają wyszukiwarkę i sekcję „podobne produkty" na żywych sklepach klientów SwiftSearch, bezpieczne do wywoływania z przeglądarki, bo autoryzowane kluczem publicznym ograniczonym do Twojej domeny.

Autoryzacja

Każdy request wymaga dwóch nagłówków:

X-Public-Key: YOUR_PUBLIC_KEY
Origin: https://twoj-sklep.pl

Swój klucz publiczny znajdziesz w panelu po zalogowaniu, razem z pełnym, interaktywnym referencem API (włącznie z endpointami do dodawania i usuwania produktów).

POST

/search

Request body (JSON):

{
  "q": "telewizor",
  "page": 1,
  "categories": [],
  "manufacturers": [],
  "filters": []
}

Przykład (cURL)

curl -X POST https://api.swiftsearch.pl/search \
  -H 'Content-Type: application/json' \
  -H 'X-Public-Key: YOUR_PUBLIC_KEY' \
  -H 'Origin: https://twoj-sklep.pl' \
  -d '{"q":"telewizor"}'

Response (200 OK)

{
  "products": [
    {
      "id": "1100",
      "name": "Telewizor Neo QLED 75 cali 8K",
      "sku": "TV8K75",
      "slug": "telewizor-neo-qled-75-8k",
      "brand": "Samsung",
      "price": 3499,
      "sale_price": 0,
      "currency": "PLN",
      "in_stock": true,
      "stock_quantity": 4,
      "image": "https://example.com/img/tv8k75.jpg",
      "url": "https://example.com/telewizor-neo-qled-75-8k"
    }
  ],
  "facets": [
    { "name": "Kategorie", "searchName": "categories", "values": [{ "name": "RTV", "value": 24 }] }
  ],
  "meta": { "total_found": 24, "page": 1, "per_page": 20, "total_pages": 2 },
  "duration_ms": "8 ms"
}
GET

/similar (produkty podobne do wskazanego)

Parametry query string:

Parametr Opis Domyślnie
product_id ID produktu, do którego szukamy podobnych (wymagane) -
limit Liczba zwracanych produktów (1–24) 6

Przykład (cURL)

curl 'https://api.swiftsearch.pl/similar?product_id=1100&limit=6' \
  -H 'X-Public-Key: YOUR_PUBLIC_KEY' \
  -H 'Origin: https://twoj-sklep.pl'

Response (200 OK)

{
  "products": [
    {
      "id": "1101",
      "name": "Telewizor Neo QLED 65 cali 8K",
      "sku": "TV8K65",
      "price": 2899,
      "sale_price": 0,
      "in_stock": true,
      "brand": "Samsung",
      "categories": ["RTV"],
      "image": "https://example.com/img/tv8k65.jpg",
      "url": "https://example.com/telewizor-neo-qled-65-8k"
    }
  ]
}

Endpoint wymaga włączonego wyszukiwania semantycznego (AI) dla katalogu, dostępnego od planu Business.

Dodawanie, aktualizowanie i usuwanie produktów w indeksie odbywa się przez osobne, uwierzytelnione endpointy, których celowo nie publikujemy tutaj szczegółowo. Ich pełny opis jest dostępny w panelu po zalogowaniu, żeby nie ułatwiać prób nieautoryzowanej ingerencji w cudze katalogi.

Kody błędów HTTP

400 Bad Request Brak wymaganych parametrów lub niepoprawny JSON.
401 Unauthorized Brak klucza publicznego lub niepoprawny klucz / domena.
402 Payment Required Przekroczony limit planu (np. liczba produktów).
403 Forbidden Projekt nieaktywny.
429 Too Many Requests Przekroczony limit requestów na sekundę.
503 Service Unavailable Chwilowy problem z usługą wyszukiwania.

Zobacz pełną, interaktywną dokumentację ze swoim kluczem

Po założeniu konta panel pokazuje gotowe do wklejenia przykłady z Twoim prawdziwym kluczem publicznym, dla wszystkich endpointów, łącznie z importem i zarządzaniem katalogiem.

Pytania? Napisz na kamil@swiftsearch.pl

🍪

Używamy niezbędnych plików cookies do poprawnego działania serwisu. Więcej w polityce prywatności.