כיצד להשתמש ב-API של Shoply AI Search

כן. אפשר לבצע שאילתות ל-Shoply AI Search באופן תכנותי מה-backend שלכם בלי לטעון את הווידג’ט באתר ובלי לשלוח את הבקשה דרך חנות ה-Shopify שלכם.

ה-API הסטנדרטי לחיפוש זמין בכל תוכנית Shopify שכוללת AI Search, כולל Forever Free. בקשות API משתמשות באותה מכסת חיפושים חודשית כמו חיפושים שמתבצעים דרך הווידג’ט בחזית החנות. את המגבלות העדכניות אפשר לראות בעמוד התמחור שלנו.

אם אתם צריכים מגבלות גבוהות יותר, הסכם רמת שירות, מקור נתונים מותאם אישית או אינטגרציה שלא משתמשת בקטלוג Shopify שאונדקס על ידי Shoply, צרו איתנו קשר לגבי תוכנית Enterprise.

לפני שמתחילים

התקינו את Shoply AI בחנות ה-Shopify שאת הקטלוג שלה אתם רוצים לחפש, והמתינו לסיום האינדוקס הראשוני של המוצרים. תצטרכו את דומיין ה-myshopify.com הקבוע של החנות, למשל:

your-store.myshopify.com

אפשר לקרוא ל-API מכל סביבת backend. אין צורך במפתח API נפרד עבור נקודת הקצה הסטנדרטית לחיפוש מוצרים, משום שהיא מחזירה את אותו מידע ציבורי על הקטלוג ש-Shoply יכולה להציג בחוויית החיפוש בחנות.

נקודת קצה

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

גוף הבקשה

query היא מחרוזת JSON בתוך גוף הבקשה, ולא אובייקט JSON מקונן. לדוגמה, ביטוי החיפוש waterproof hiking boots נשלח כך:

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

דוגמת cURL

החליפו את your-store.myshopify.com בדומיין ה-Shopify הקבוע של החנות שלכם:

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

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

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

תגובה

בקשה מוצלחת מחזירה:

{
  "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 הוא המספר הכולל של מוצרים תואמים.
• docs מכיל את המוצרים המדורגים עבור הדף שהתבקש.
• display_filters מכיל מסננים זמינים כמו מחיר, מותג, צבע או מאפיינים אחרים הספציפיים לקטלוג.

אובייקטי מוצר עשויים להכיל שדות נוספים בהתאם לקטלוג החנות, הווריאנטים, התמחור וההגדרות של Shoply. לקוחות צריכים להשתמש בשדות הדרושים להם ולהתעלם בבטחה משדות לא מוכרים.

עימוד

השתמשו ב-start וב-limit כדי לבקש תוצאות נוספות. לדוגמה, אחרי שביקשתם שמונה מוצרים עם start: 0 ו-limit: 8, בקשו את הדף הבא באמצעות:

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

עצרו כאשר start + docs.length גדול או שווה ל-num_results, או כאשר docs ריק.

הערות על תוכניות ואינטגרציה

אם חזית החנות המותאמת שלכם צריכה גם שיחה, הוסיפו צ’אט לחנות Shopify headless.

• חיפוש API סטנדרטי הוא בשירות עצמי ואינו דורש את הווידג’ט באתר.
• חנות ה-Shopify שלכם חייבת להישאר מחוברת ל-Shoply AI כדי שאינדקס המוצרים שלה יישאר מעודכן.
• חיפושי API וחיפושי חזית החנות חולקים את מכסת החיפושים החודשית של תוכנית ה-Shopify שלכם.
• שמרו את הקריאה ב-backend שלכם אם אתם רוצים לרכז caching, logging, retries או בקרת גישה.
• צרו איתנו קשר לקבלת תמיכת Enterprise אם אתם צריכים אימות מותאם אישית, קצב עיבוד מובטח, SLA, קטלוג שאינו Shopify או מגבלות מעבר לתוכניות המפורסמות.

לעזרה באישור מפתח החנות שלכם או בתכנון אינטגרציה לסביבת production, צרו קשר עם Shoply AI.