Hoe je de Shoply AI Search API gebruikt

Ja. Je kunt Shoply AI Search programmatisch bevragen vanuit je eigen backend zonder de on-site widget te laden of het verzoek via je Shopify-storefront te versturen.

De standaard search API is beschikbaar bij elk Shopify-plan dat AI Search bevat, inclusief Forever Free. API-verzoeken gebruiken dezelfde maandelijkse zoeklimiet als zoekopdrachten die via de storefront-widget worden uitgevoerd. Bekijk de actuele limieten op onze pricing page.

Als je hogere limieten, een service-level agreement, een aangepaste databron of een integratie nodig hebt die geen door Shoply geïndexeerde Shopify-catalogus gebruikt, neem contact met ons op over een Enterprise-plan.

Voordat je begint

Installeer Shoply AI op de Shopify-store waarvan je de catalogus wilt doorzoeken en laat de initiële productindexering voltooien. Je hebt het permanente myshopify.com-domein van de store nodig, zoals:

your-store.myshopify.com

De API kan vanuit elke backend-omgeving worden aangeroepen. Een aparte API-sleutel is niet vereist voor het standaard endpoint voor productzoekopdrachten, omdat dit dezelfde openbare catalogusinformatie retourneert die Shoply in de storefront-zoekervaring kan tonen.

Endpoint

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

Requestbody

query is een JSON-string binnen de requestbody, geen genest JSON-object. De zoekterm waterproof hiking boots wordt bijvoorbeeld verzonden als:

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

cURL-voorbeeld

Vervang your-store.myshopify.com door het permanente Shopify-domein van je store:

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-voorbeeld

// 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-voorbeeld

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

Een succesvol verzoek retourneert:

{
  "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 is het totale aantal overeenkomende producten.
• docs bevat de gerangschikte producten voor de opgevraagde pagina.
• display_filters bevat beschikbare filters zoals prijs, merk, kleur of andere catalogusspecifieke kenmerken.

Productobjecten kunnen aanvullende velden bevatten, afhankelijk van de catalogus van de store, varianten, prijzen en de Shoply-configuratie. Clients moeten de velden gebruiken die ze nodig hebben en onbekende velden veilig negeren.

Paginering

Gebruik start en limit om extra resultaten op te vragen. Als je bijvoorbeeld eerst acht producten opvraagt met start: 0 en limit: 8, vraag je de volgende pagina op met:

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

Stop wanneer start + docs.length groter is dan of gelijk aan num_results, of wanneer docs leeg is.

Opmerkingen over plannen en integratie

Als je aangepaste storefront ook conversatie nodig heeft, voeg chat toe aan een headless Shopify-storefront.

• Standaard API-zoekopdrachten zijn self-service en vereisen de on-site widget niet.
• Je Shopify-store moet verbonden blijven met Shoply AI zodat de productindex actueel kan blijven.
• API-zoekopdrachten en storefront-zoekopdrachten delen de maandelijkse zoeklimiet van je Shopify-plan.
• Houd de aanroep in je backend als je caching, logging, retries of toegangscontrole wilt centraliseren.
• Neem contact met ons op voor Enterprise-ondersteuning als je aangepaste authenticatie, gegarandeerde throughput, een SLA, een niet-Shopify-catalogus of limieten buiten de gepubliceerde plannen nodig hebt.

Voor hulp bij het bevestigen van je store key of het plannen van een productie-integratie, neem contact op met Shoply AI.