So verwendest du die Shoply AI Search API

Ja. Du kannst Shoply AI Search programmatisch über dein eigenes Backend abfragen, ohne das On-Site-Widget zu laden oder die Anfrage über dein Shopify-Storefront zu senden.

Die Standard-Such-API ist in jedem Shopify-Tarif mit AI Search verfügbar, einschließlich Forever Free. API-Anfragen verwenden dasselbe monatliche Suchkontingent wie Suchen, die über das Storefront-Widget durchgeführt werden. Die aktuellen Limits findest du auf unserer Preisseite.

Wenn du höhere Limits, ein Service Level Agreement, eine benutzerdefinierte Datenquelle oder eine Integration benötigst, die keinen von Shoply indexierten Shopify-Katalog verwendet, kontaktiere uns wegen eines Enterprise-Tarifs.

Bevor du beginnst

Installiere Shoply AI im Shopify-Store, dessen Katalog du durchsuchen möchtest, und warte, bis die initiale Produktindexierung abgeschlossen ist. Du benötigst die permanente myshopify.com-Domain des Stores, zum Beispiel:

your-store.myshopify.com

Die API kann aus jeder Backend-Umgebung aufgerufen werden. Für den Standard-Endpunkt zur Produktsuche ist kein separater API-Schlüssel erforderlich, da er dieselben öffentlichen Kataloginformationen zurückgibt, die Shoply auch in der Storefront-Sucherfahrung anzeigen kann.

Endpunkt

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

Request-Body

query ist ein JSON-String innerhalb des Request-Bodys, kein verschachteltes JSON-Objekt. Zum Beispiel wird die Suchphrase waterproof hiking boots so gesendet:

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

cURL-Beispiel

Ersetze your-store.myshopify.com durch die permanente Shopify-Domain deines Stores:

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

JavaScript-Beispiel

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

Python-Beispiel

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

Response

Eine erfolgreiche Anfrage gibt Folgendes zurück:

{
  "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 ist die Gesamtzahl der passenden Produkte.
• docs enthält die nach Relevanz sortierten Produkte für die angeforderte Seite.
• display_filters enthält verfügbare Filter wie Preis, Marke, Farbe oder andere katalogspezifische Attribute.

Produktobjekte können abhängig vom Katalog des Stores, Varianten, Preisen und der Shoply-Konfiguration zusätzliche Felder enthalten. Clients sollten die Felder verwenden, die sie benötigen, und unbekannte Felder sicher ignorieren.

Paginierung

Verwende start und limit, um weitere Ergebnisse anzufordern. Wenn du zum Beispiel acht Produkte mit start: 0 und limit: 8 angefordert hast, fordere die nächste Seite an mit:

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

Beende den Vorgang, wenn start + docs.length größer oder gleich num_results ist oder wenn docs leer ist.

Hinweise zu Tarif und Integration

Wenn dein benutzerdefiniertes Storefront auch Konversation benötigt, füge Chat zu einem headless Shopify-Storefront hinzu.

• Die Standard-API-Suche ist Self-Service und erfordert nicht das On-Site-Widget.
• Dein Shopify-Store muss mit Shoply AI verbunden bleiben, damit sein Produktindex aktuell gehalten werden kann.
• API-Suchen und Storefront-Suchen teilen sich das monatliche Suchkontingent deines Shopify-Tarifs.
• Belasse den Aufruf in deinem Backend, wenn du Caching, Logging, Wiederholungen oder Zugriffskontrolle zentralisieren möchtest.
• Kontaktiere uns für Enterprise-Support, wenn du benutzerdefinierte Authentifizierung, garantierten Durchsatz, ein SLA, einen Nicht-Shopify-Katalog oder Limits über die veröffentlichten Tarife hinaus benötigst.

Wenn du Hilfe bei der Bestätigung deines Store-Keys oder bei der Planung einer Produktionsintegration benötigst, kontaktiere Shoply AI.