كيفية رفع كتالوجك إلى SiteChat

إذا كنت تستخدم SiteChat على موقعك الإلكتروني الخاص (وليس متجر Shopify)، يمكنك إرسال سجلات منتجات منظَّمة إلى Shoply حتى يتمكن المتسوقون من العثور عليها في دردشة SiteChat وفي بحث المنتجات.

تستخدم نقاط النهاية هذه نفس Settings → Store owner API secret المستخدم في باقي Shoply Merchant API، ويمكن لصفحة Product Catalog في لوحة إدارة SiteChat استدعاءها باستخدام رمز وصول الإدارة الخاص بك أثناء تسجيل الدخول. تستمر متاجر Shopify في مزامنة بيانات الكتالوج عبر Shopify؛ ومسارات الرفع هذه متاحة فقط لحسابات SiteChat التي لا تقوم بالفعل بمزامنة كتالوج Magento.

في لوحة إدارة SiteChat، تفتح Product Catalog مساحة بأسلوب Shopify تتضمن Products وCollections وInventory. يمكنك إضافة المنتجات أو تعديلها، واستيراد CSV/Excel، وتجميع المنتجات في مجموعات يدوية، وضبط كميات المخزون.

ما واجهات برمجة التطبيقات المتاحة؟

عمليات حفظ المنتجات الناجحة تطلب من Shoply إعادة بناء فهرس المتجر. وحتى يكتمل هذا البناء، ستعرض الاستجابات index_status: "pending". بعد ذلك تظهر المنتجات المنشورة في كلٍّ من فهرس المنتجات والمعرفة المستخدمة في دردشة SiteChat.

من يمكنه استخدام واجهات برمجة التطبيقات هذه؟

• يجب أن يكون متجرك حساب SiteChat (app_platform يساوي SiteChat).
• يتم رفض مفاتيح متاجر Shopify (بما في ذلك أي نطاق *.myshopify.com).
• يجب أن تستخدم المصادقة إما سرًا صالحًا لواجهة برمجة تطبيقات مالك المتجر أو رمز وصول لإدارة SiteChat يخص store_key نفسه الموجود في الطلب.
• لا يمكن لرموز Shopify Admin API استدعاء هذه المسارات.

أنشئ سر المالك أو بدّله بالطريقة نفسها المستخدمة في تكاملات Merchant API الأخرى: كيفية استخدام Shoply Merchant API. في وحدة إدارة SiteChat، افتح Product Catalog لإدارة المنتجات والمجموعات والمخزون — أو لاستيراد ملف CSV أو Excel — بدون الحاجة إلى إدارة السر بنفسك.

كيف تعمل المصادقة؟

من موصل خادوم

استدعِ واجهة برمجة التطبيقات من خلفية موثوقة عبر HTTPS. ضع سلسلة JSON في ترويسة Authorization:

{
  "store_key": "YOUR_SITECHAT_STORE_KEY",
  "store_owner_api_secrete": "YOUR_STORE_OWNER_API_SECRET"
}

store_owner_api_secrete هو اسم الحقل العام، بما في ذلك التهجئة التاريخية. كما يتم قبول store_owner_api_secret أيضًا. هذا ليس رمز Bearer.

من لوحة إدارة SiteChat

ترسل صفحة Product Catalog جلسة الإدارة الخاصة بك أثناء تسجيل الدخول بدلًا من ذلك:

{
  "store_key": "YOUR_SITECHAT_STORE_KEY",
  "admin_auth_token": "YOUR_SITECHAT_ACCESS_TOKEN"
}

يتم قبول access_token كاسم بديل لـ admin_auth_token.

يجب أن يطابق معامِل الاستعلام store_key الترويسة. احتفظ بأسرار المالك في متغيرات بيئة على جانب الخادوم فقط — ولا تضعها أبدًا في سكربت واجهة المتجر أو في عنوان URL أو في مستودع عام.

export SHOPLY_STORE_KEY="your-sitechat-store-key"
export SHOPLY_STORE_OWNER_API_SECRETE="shoply_owner_key_example123.secret-value"

كيف أرفع المنتجات؟

POST https://api.shoplyai.ai/merchant/products/batch?store_key=YOUR_SITECHAT_STORE_KEY

{
  "source": "woocommerce-main",
  "products": [
    {
      "external_id": "123",
      "title": "Trail shoes",
      "description": "Water-resistant hiking shoes.",
      "url": "https://example.com/products/trail-shoes",
      "currency": "USD",
      "price": "49.95",
      "original_price": "59.95",
      "available": true,
      "status": "published",
      "images": ["https://example.com/images/trail-shoes.jpg"],
      "categories": ["Footwear"],
      "metafields": {"material": "Leather"},
      "variants": [
        {
          "external_id": "124",
          "title": "Brown / 42",
          "sku": "TRAIL-BR-42",
          "price": "49.95",
          "available": true,
          "metafields": {"color": "Brown", "size": "42"}
        }
      ]
    }
  ]
}

الحقول والقواعد المطلوبة

• الحقول المطلوبة للمنتج: external_id وtitle وurl وcurrency وprice وavailable. القيمة الافتراضية لـ status هي published.
• المخزون الاختياري: اضبط tracks_inventory على true وحدد quantity غير سالبة على المنتج أو المتغير. عندها يستنتج Shoply التوفر من المخزون (quantity > 0) ويخزن total_inventory لقوائم الإدارة.
• يحدد source اسم اتصال الكتالوج (وليس بالضرورة منصة). استخدم اسمًا ثابتًا مثل woocommerce-main. الأحرف المسموح بها: أحرف إنجليزية صغيرة، وأرقام، وشرطات سفلية، وواصلات؛ وبحد أقصى 64 حرفًا. المنتجات التي تُنشأ عبر النماذج في لوحة الإدارة تستخدم المصدر الافتراضي admin.
• هوية المنتج هي مزيج من المتجر والمصدر والمعرف الخارجي. عمليات upsert المجمعة والمفردة عبر POST هي استبدالات كاملة وليست ترقيعات: الحقول الاختيارية المحذوفة يتم مسحها. استخدم PATCH للتحديثات الجزئية.
• تحتوي الدُفعات على 1–50 منتجًا وبحد أقصى 2,000,000 بايت للطلب. JSON المتحقق منه لكل منتج محدود بـ 128,000 بايت، وبحد أقصى 250 متغيرًا.
• يُفضَّل استخدام سلاسل عشرية للأسعار. ويجب أن تكون العملة رمزًا من ثلاثة أحرف كبيرة.
• يجب أن تكون روابط المنتجات والصور من نوع HTTP(S). لا يقوم الاستيراد بجلب هذه الروابط نيابةً عنك.
• استخدم metafields العامة لمواصفات المنتجات القابلة للبحث (وهي المقابل في SiteChat لحقول Shopify الوصفية للمنتجات). يجب أن تكون القيم سلاسل نصية عادية. كما يتم قبول attributes القديمة كاسم بديل. لم يعد metadata الخاص بالمنتج مدعومًا.
• يتم استبعاد المنتجات draft وarchived من الفهرس المنشور التالي. أما المنتجات المنشورة النافدة فتبقى مفهرسة مع إرفاق حالة التوفر.
• تخزن المجموعات اليدوية عنوانًا ووصفًا وحالةً وقائمةً بعضويات المنتجات (source + external_id). المجموعات الذكية/المعتمدة على القواعد غير مدعومة في هذا الإصدار.

مثال على استجابة نجاح

{
  "results": [
    {
      "external_id": "123",
      "product_id": "sitechat_product::woocommerce-main::<sha256-of-external-id>",
      "status": "stored"
    }
  ],
  "index_status": "pending",
  "index_revision": 1
}

يتحقق Shoply من الطلب كاملًا قبل الكتابة. يمكن أن تتضمن استجابة HTTP 200 بعض النتائج ضمن failed مع error: "storage_error". افحص كل نتيجة وأعد المحاولة للمنتجات الفاشلة. إذا كانت index_status تساوي request_failed، فهذا يعني أن التخزين نجح لكن لم تتم جدولة الفهرسة — لذا أعد محاولة المنتجات المخزنة أيضًا.

مثال Python

import json
import os
import requests
 
store_key = os.environ["SHOPLY_STORE_KEY"]
headers = {
    "Authorization": json.dumps({
        "store_key": store_key,
        "store_owner_api_secrete": os.environ["SHOPLY_STORE_OWNER_API_SECRETE"],
    })
}
 
response = requests.post(
    "https://api.shoplyai.ai/merchant/products/batch",
    params={"store_key": store_key},
    headers=headers,
    json={
        "source": "custom",
        "products": [{
            "external_id": "123",
            "title": "Trail shoes",
            "url": "https://example.com/products/trail-shoes",
            "currency": "USD",
            "price": "49.95",
            "available": True,
        }],
    },
    timeout=60,
)
response.raise_for_status()
result = response.json()
failed = [item["external_id"] for item in result["results"] if item["status"] != "stored"]
if failed:
    raise RuntimeError(f"Products need retry: {failed}")
if result["index_status"] == "request_failed":
    raise RuntimeError("Products saved, but retry the batch to request indexing")

كيف أتحقق من منتج مستورد؟

GET https://api.shoplyai.ai/merchant/products?store_key=YOUR_SITECHAT_STORE_KEY&source=woocommerce-main&external_id=123

استخدم ترويسة Authorization نفسها. تتضمن الاستجابة schema_version وupdated_at وindex_status وproduct بعد التسوية. السجلات غير الموجودة تُرجع HTTP 404.

بعد أن ينشر المفهرس في الخلفية عملية إعادة البناء، تصبح حالة القراءة الخاصة بكل منتج indexed أو excluded (للمنتجات المسودة أو المؤرشفة) أو limit_exceeded. استخدم GET /merchant/products/list لسرد المنتجات في لوحة الإدارة. قم بالأرشفة المرنة باستخدام DELETE /merchant/products (أو اضبط status إلى archived / draft) لإبقاء المنتج خارج الفهرس المنشور التالي؛ ولا يوجد حذف نهائي في هذا الإصدار.

record = requests.get(
    "https://api.shoplyai.ai/merchant/products",
    params={
        "store_key": store_key,
        "source": "woocommerce-main",
        "external_id": "123",
    },
    headers=headers,
    timeout=30,
)
record.raise_for_status()
print(record.json()["index_status"], record.json()["product"]["title"])

هل يمكنني رفع صور المنتجات؟

نعم. إذا كانت الصورة متاحة بالفعل عبر رابط HTTPS عام ثابت، فضع ذلك الرابط في قائمة images الخاصة بالمنتج أو في الحقل image الخاص بالمتغير. تعمل روابط S3 العامة عبر HTTPS. أما مسارات s3:// الخام والروابط الموقعة قصيرة العمر فلا تعمل.

لكي يستضيف Shoply الملف، ارفع بايتات الصورة الخام من خدمتك الخلفية:

POST https://api.shoplyai.ai/merchant/products/images?store_key=YOUR_SITECHAT_STORE_KEY
Content-Type: image/png

أرسل بايتات الملف الخام، وليس JSON أو base64 أو بيانات نموذج multipart. يتم قبول JPEG وPNG وWebP، حتى 10 MiB و20 مليون بكسل. الصور المتحركة غير مدعومة. يحول Shoply الصورة إلى WebP ويزيل البيانات الوصفية المضمّنة.

with open("trail-shoes.png", "rb") as image_file:
    response = requests.post(
        "https://api.shoplyai.ai/merchant/products/images",
        params={"store_key": store_key},
        headers={**headers, "Content-Type": "image/png"},
        data=image_file,
        timeout=60,
    )
response.raise_for_status()
image_url = response.json()["url"]

يعيد HTTP 201 القيم url وcontent_type وsize_bytes وwidth وheight. رفع صورة وحدها لا يربطها بمنتج ولا يطلب الفهرسة. أدرج الرابط المُعاد في منتج كامل ثم أرسله مرة أخرى عبر /merchant/products/batch.

إذا رُفعت الصورة نفسها مرة أخرى للحساب نفسه، فسيُعاد استخدام رابطها. أما الصورة المتغيرة فستحصل على رابط جديد. لا توجد نقطة نهاية لحذف الصور في هذا الإصدار.

متى تظهر المنتجات في الدردشة والبحث؟

بعد حفظ دفعة بنجاح، يطلب Shoply إعادة بناء الفهرس في الخلفية. تعرض الاستجابات index_status: "pending" حتى ينشر العامل الفهرس الجديد. لا يوجد ضمان زمني ثابت للاكتمال.

• تدخل المنتجات المنشورة في كلٍّ من بحث المنتجات والمعرفة المستخدمة في دردشة SiteChat.
• يتم استبعاد المنتجات المسودة والمؤرشفة عند إعادة البناء التالية.
• إذا لم تتم جدولة الفهرسة (index_status: "request_failed")، فأعد محاولة الدفعة للمنتجات التي تم تخزينها بنجاح بالفعل.

ما الأخطاء التي ينبغي أن أتوقعها؟

تنتهي صلاحية الأسرار بعد 90 يومًا. أنشئ بديلًا في Settings → Store owner API secret قبل انتهاء الصلاحية، وألغِ أي سر لم تعد بحاجة إليه. يمكن للسر نفسه أيضًا استدعاء نقاط نهاية التحليلات والمحادثات والمعرفة الموثقة في دليل Merchant API.

للحصول على مساعدة بشأن أي تكامل، تواصل مع Shoply AI.