كيفية استخدام واجهة برمجة تطبيقات Shoply AI Search

نعم. يمكنك الاستعلام من Shoply AI Search برمجيًا من خلال الواجهة الخلفية الخاصة بك دون تحميل الأداة المصغّرة الموجودة على الموقع أو إرسال الطلب عبر واجهة متجر Shopify الخاصة بك.

واجهة برمجة تطبيقات البحث القياسية متاحة مع كل خطة Shopify تتضمن AI Search، بما في ذلك Forever Free. تستخدم طلبات API نفس مخصص البحث الشهري المستخدم لعمليات البحث التي تتم عبر أداة واجهة المتجر. اطّلع على الحدود الحالية في صفحة الأسعار.

إذا كنت بحاجة إلى حدود أعلى، أو اتفاقية مستوى خدمة، أو مصدر بيانات مخصص، أو تكامل لا يستخدم كتالوج Shopify مفهرسًا بواسطة Shoply، تواصل معنا بشأن خطة Enterprise.

قبل أن تبدأ

ثبّت Shoply AI على متجر Shopify الذي تريد البحث في كتالوجه، واسمح بانتهاء الفهرسة الأولية للمنتجات. ستحتاج إلى نطاق myshopify.com الدائم الخاص بالمتجر، مثل:

your-store.myshopify.com

يمكن استدعاء واجهة برمجة التطبيقات من أي بيئة خلفية. لا يلزم مفتاح 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 بدون واجهة أمامية تقليدية.

• البحث عبر API القياسي خدمة ذاتية ولا يتطلب الأداة المصغّرة الموجودة على الموقع.
• يجب أن يظل متجر Shopify الخاص بك متصلاً بـ Shoply AI حتى يظل فهرس منتجاته محدثًا.
• تشترك عمليات البحث عبر API وعمليات البحث في واجهة المتجر في مخصص البحث الشهري الخاص بخطة Shopify لديك.
• احتفظ بالاستدعاء في الواجهة الخلفية إذا كنت تريد توحيد التخزين المؤقت أو التسجيل أو إعادة المحاولة أو التحكم في الوصول.
• تواصل معنا للحصول على دعم Enterprise إذا كنت بحاجة إلى مصادقة مخصصة، أو معدل نقل مضمون، أو SLA، أو كتالوج غير تابع لـ Shopify، أو حدود تتجاوز الخطط المنشورة.

للحصول على مساعدة في تأكيد مفتاح متجرك أو التخطيط لتكامل إنتاجي، تواصل مع Shoply AI.