Jak korzystać z interfejsu API wyszukiwania Shoply AI

Tak. Możesz programowo wykonywać zapytania do Shoply AI Search z własnego backendu bez ładowania widżetu na stronie ani wysyłania żądania przez storefront Shopify.

Standardowy interfejs API wyszukiwania jest dostępny w każdym planie Shopify obejmującym AI Search, w tym Forever Free. Żądania API korzystają z tego samego miesięcznego limitu wyszukiwań co wyszukiwania wykonywane przez widżet storefrontu. Aktualne limity znajdziesz na naszej stronie z cennikiem.

Jeśli potrzebujesz wyższych limitów, umowy SLA, niestandardowego źródła danych lub integracji, która nie korzysta z katalogu Shopify indeksowanego przez Shoply, skontaktuj się z nami w sprawie planu Enterprise.

Zanim zaczniesz

Zainstaluj Shoply AI w sklepie Shopify, którego katalog chcesz przeszukiwać, i poczekaj na zakończenie początkowego indeksowania produktów. Będziesz potrzebować stałej domeny myshopify.com sklepu, na przykład:

your-store.myshopify.com

API można wywoływać z dowolnego środowiska backendowego. Oddzielny klucz API nie jest wymagany dla standardowego endpointu wyszukiwania produktów, ponieważ zwraca on te same publiczne informacje o katalogu, które Shoply może wyświetlać w wyszukiwaniu na storefrontcie.

Endpoint

POST https://api.shoplyai.ai/product_query_v2
Content-Type: application/json

Treść żądania

query jest ciągiem JSON wewnątrz treści żądania, a nie zagnieżdżonym obiektem JSON. Na przykład fraza wyszukiwania waterproof hiking boots jest wysyłana jako:

"{\"keywords\":\"waterproof hiking boots\"}"

Przykład cURL

Zastąp your-store.myshopify.com stałą domeną Shopify swojego sklepu:

curl --request POST "https://api.shoplyai.ai/product_query_v2" \
  --header "Content-Type: application/json" \
  --data '{
    "store_key": "your-store.myshopify.com",
    "query": "{\"keywords\":\"waterproof hiking boots\"}",
    "start": 0,
    "limit": 8
  }'

Przykład JavaScript

// Build the inner query separately because the API expects it as a JSON-encoded string.
const searchQuery = JSON.stringify({
  keywords: "waterproof hiking boots"
});
 
const response = await fetch("https://api.shoplyai.ai/product_query_v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    store_key: "your-store.myshopify.com",
    query: searchQuery,
    start: 0,
    limit: 8
  })
});
 
if (!response.ok) {
  throw new Error(`Shoply search failed with status ${response.status}`);
}
 
const results = await response.json();
console.log(results.docs);

Przykład Python

import json
import requests
 
# The query value is encoded separately to match Shoply's structured search contract.
payload = {
    "store_key": "your-store.myshopify.com",
    "query": json.dumps({"keywords": "waterproof hiking boots"}),
    "start": 0,
    "limit": 8,
}
 
response = requests.post(
    "https://api.shoplyai.ai/product_query_v2",
    json=payload,
    timeout=30,
)
response.raise_for_status()
 
results = response.json()
print(results["docs"])

Odpowiedź

Pomyślne żądanie zwraca:

{
  "num_results": 2,
  "docs": [
    {
      "product_id": "gid://shopify/Product/1234567890",
      "url": "https://your-store.example/products/example-product",
      "product_name": "Example Product",
      "brand": "Example Brand",
      "current_price": "129.00",
      "currency": "USD",
      "main_image": "https://cdn.shopify.com/example-product.jpg",
      "selected_variant_id": "gid://shopify/ProductVariant/1234567891"
    }
  ],
  "display_filters": []
}

• num_results to łączna liczba pasujących produktów.
• docs zawiera uszeregowane produkty dla żądanej strony.
• display_filters zawiera dostępne filtry, takie jak cena, marka, kolor lub inne atrybuty specyficzne dla katalogu.

Obiekty produktów mogą zawierać dodatkowe pola zależnie od katalogu sklepu, wariantów, cen i konfiguracji Shoply. Klienci powinni używać potrzebnych im pól i bezpiecznie ignorować nieznane pola.

Paginacja

Użyj start i limit, aby pobrać kolejne wyniki. Na przykład po pobraniu ośmiu produktów z start: 0 i limit: 8 pobierz następną stronę za pomocą:

{
  "start": 8,
  "limit": 8
}

Zatrzymaj się, gdy start + docs.length jest większe lub równe num_results, albo gdy docs jest puste.

Uwagi dotyczące planu i integracji

Jeśli Twój niestandardowy storefront również potrzebuje funkcji konwersacji, dodaj czat do headless storefrontu Shopify.

• Standardowe wyszukiwanie API jest samoobsługowe i nie wymaga widżetu na stronie.
• Twój sklep Shopify musi pozostać połączony z Shoply AI, aby indeks produktów był aktualny.
• Wyszukiwania API i wyszukiwania w storefrontcie współdzielą miesięczny limit wyszukiwań dla Twojego planu Shopify.
• Zachowaj to wywołanie w swoim backendzie, jeśli chcesz scentralizować cache’owanie, logowanie, ponawianie prób lub kontrolę dostępu.
• Skontaktuj się z nami w sprawie wsparcia Enterprise, jeśli potrzebujesz niestandardowego uwierzytelniania, gwarantowanej przepustowości, SLA, katalogu spoza Shopify lub limitów wykraczających poza opublikowane plany.

Jeśli potrzebujesz pomocy z potwierdzeniem klucza sklepu lub zaplanowaniem integracji produkcyjnej, skontaktuj się z Shoply AI.