كيفية الوصول إلى Shoply AI Search عبر واجهة API

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

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

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

قبل أن تبدأ

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

your-store.myshopify.com

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