Jak používat Shoply AI Search API

Ano. Shoply AI Search můžete programově dotazovat z vlastního backendu bez načítání widgetu na webu nebo odesílání požadavku přes váš Shopify storefront.

Standardní vyhledávací API je k dispozici u každého Shopify plánu, který zahrnuje AI Search, včetně Forever Free. API požadavky používají stejný měsíční limit vyhledávání jako vyhledávání prováděná přes widget ve storefrontu. Aktuální limity najdete na naší stránce s cenami.

Pokud potřebujete vyšší limity, smlouvu SLA, vlastní zdroj dat nebo integraci, která nepoužívá Shopify katalog indexovaný pomocí Shoply, kontaktujte nás ohledně Enterprise plánu.

Než začnete

Nainstalujte Shoply AI do Shopify obchodu, jehož katalog chcete prohledávat, a nechte dokončit počáteční indexaci produktů. Budete potřebovat trvalou doménu obchodu myshopify.com, například:

your-store.myshopify.com

API lze volat z jakéhokoli backendového prostředí. Pro standardní endpoint vyhledávání produktů není vyžadován samostatný API klíč, protože vrací stejné veřejné informace o katalogu, které může Shoply zobrazit ve storefront vyhledávání.

Endpoint

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

Tělo požadavku

query je JSON řetězec uvnitř těla požadavku, nikoli vnořený JSON objekt. Například hledaná fráze waterproof hiking boots se odesílá takto:

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

Příklad cURL

Nahraďte your-store.myshopify.com trvalou Shopify doménou svého obchodu:

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
  }'

Příklad v JavaScriptu

// 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);

Příklad v Pythonu

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"])

Odpověď

Úspěšný požadavek vrací:

{
  "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 je celkový počet odpovídajících produktů.
• docs obsahuje seřazené produkty pro požadovanou stránku.
• display_filters obsahuje dostupné filtry, například cenu, značku, barvu nebo jiné atributy specifické pro katalog.

Objekty produktů mohou obsahovat další pole v závislosti na katalogu obchodu, variantách, cenách a konfiguraci Shoply. Klienti by měli používat pole, která potřebují, a neznámá pole bezpečně ignorovat.

Stránkování

Pomocí start a limit si vyžádejte další výsledky. Například po vyžádání osmi produktů s start: 0 a limit: 8 si další stránku vyžádejte takto:

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

Přestaňte, když start + docs.length je větší nebo rovno num_results, nebo když je docs prázdné.

Poznámky k plánům a integraci

Pokud váš vlastní storefront potřebuje také konverzaci, přidejte chat do headless Shopify storefrontu.

• Standardní vyhledávání přes API je samoobslužné a nevyžaduje widget na webu.
• Váš Shopify obchod musí zůstat připojený k Shoply AI, aby jeho index produktů mohl zůstat aktuální.
• Vyhledávání přes API a vyhledávání ve storefrontu sdílejí měsíční limit vyhledávání pro váš Shopify plán.
• Pokud chcete centralizovat cache, logování, opakování požadavků nebo řízení přístupu, ponechte volání na svém backendu.
• Pokud potřebujete vlastní autentizaci, garantovanou propustnost, SLA, katalog mimo Shopify nebo limity nad rámec zveřejněných plánů, kontaktujte nás kvůli podpoře Enterprise.

Pokud potřebujete pomoc s potvrzením klíče obchodu nebo plánováním produkční integrace, kontaktujte Shoply AI.