كيفية استخدام Shoply Merchant API

تتيح Shoply Merchant API للتاجر استخدام بيانات Shoply الخاصة به بأمان داخل أدوات إعداد التقارير، وسير عمل الدعم، وعمليات التصدير المجدولة، وتطبيقات الأعمال الخاصة.

يتم توثيق كل تكامل باستخدام بيانات اعتماد قابلة للإلغاء ومحصورة في متجر واحد، ويتم إنشاؤها من إعدادات Shoply. لا تحتاج إلى مشاركة رمز وصول Shopify Admin API، ولا يمكن لأي تكامل الوصول إلا إلى المتجر الذي أصدر بيانات الاعتماد الخاصة به.

ما الذي يمكنني فعله باستخدام Merchant API؟

يمكنك استخدام Merchant API من أجل:

• تصدير نتائج الأداء اليومية أو الأسبوعية أو الشهرية إلى جدول بيانات أو مستودع بيانات.
• إنشاء لوحة معلومات خاصة للجلسات، والمحادثات، وعمليات البحث، ونقرات المنتجات، وأحداث الإضافة إلى السلة، وعمليات الشراء، والإيرادات المنسوبة.
• مراقبة نشاط العملاء واكتشاف التغيرات غير المعتادة في التفاعل.
• مراجعة جلسات الدردشة والبحث لأعمال الدعم، والترويج التجاري، وتحسين جودة الإجابات.
• استرجاع المخطط الزمني لمحادثة فردية عند التحقيق في مشكلة عميل.
• إنشاء المعرفة المخصصة التي يستخدمها Shoply AI وتحديثها وعرضها وحذفها.
• إضافة صفحة ويب خارجية أو ملف PDF أو ملف نصي أو ملف Markdown مرفوع إلى قاعدة المعرفة.
• مواءمة بيانات الأحداث بتوقيت UTC مع المنطقة الزمنية المحلية للمتجر.

يوثق هذا الدليل سبع نقاط نهاية. خمس منها هي نفس نقاط النهاية المستخدمة بواسطة Shoply Admin → Analytics، بينما تدير اثنتان قاعدة المعرفة:

أجسام الاستجابة أدناه هي أمثلة تمثيلية. ستعكس الحقول والقيم لديك النشاط المسجل لمتجرك.

متطلب النشر: يجب نشر مصادقة سر مالك المتجر على خادم API الذي تستدعيه. إذا أعاد سر صالح HTTP 403 مع No access_token found، فهذا يعني أن ذلك الخادم لا يزال يعمل بشيفرة المصادقة الأقدم التي تعتمد فقط على access token.

كيف أنشئ سر API؟

1. افتح لوحة إدارة Shoply AI الخاصة بك.
2. انتقل إلى Settings → Store owner API secret.
3. أنشئ سرًا وامنحه اسمًا يحدد التكامل، مثل Weekly reporting export.
4. انسخ السر عند ظهوره. يعرض Shoply القيمة النصية الصريحة مرة واحدة فقط.

كل سر صالح لمدة 90 يومًا. يمكن أن يمتلك المتجر أسرارًا منفصلة لتكاملات منفصلة، ويمكنك إلغاء سر واحد دون مقاطعة الأسرار الأخرى.

احفظ هذه القيم كمتغيرات بيئة على جانب الخادم:

export SHOPLY_STORE_KEY="your-store.myshopify.com"
export SHOPLY_STORE_OWNER_API_SECRETE="shoply_owner_key_example123.secret-value"

استخدم نطاق myshopify.com الدائم الخاص بالمتجر من أجل SHOPLY_STORE_KEY، حتى إذا كان المتسوقون يزورون عادة نطاقًا مخصصًا.

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

يرسل كل طلب إلى Merchant API ترويسة Authorization تكون قيمتها سلسلة JSON:

{
  "store_key": "your-store.myshopify.com",
  "store_owner_api_secrete": "YOUR_STORE_OWNER_API_SECRET"
}

store_owner_api_secrete هو اسم الحقل العام الدقيق، بما في ذلك تهجئته التاريخية. هذا ليس رمز Bearer. ضع سلسلة JSON الكاملة مباشرة في ترويسة Authorization.

احتفظ بالسر داخل الشيفرة الخلفية فقط. لا تضعه في عنوان URL، أو حزمة المتصفح، أو مستودع عام، أو حدث تحليلات، أو سجل تطبيق.

هل توجد حزم رسمية لـ Python وNode.js؟

نعم. تنشر Shoply حزمتين من جانب الخادم تضيفان المصادقة المطلوبة تلقائيًا وتعرضان Merchant API على شكل دوال typed. كلتا الحزمتين مفتوحتا المصدر ضمن منظمة GitHub المسماة shoplyai-public.

حزمة Python

تدعم الحزمة shoply-merchant-api إصدار Python 3.12 وتستخدم نماذج استجابة Pydantic v2. ثبّت الإصدار المثبت 2.1.3:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install "git+https://github.com/shoplyai-public/shoply-merchant-api.git@v2.1.3"

استرجع أحدث جلسات الدردشة والبحث كنماذج SessionSummary typed:

import os
 
from shoply_merchant_api import ShoplyMerchantClient
 
 
with ShoplyMerchantClient(
    store_key=os.environ["SHOPLY_STORE_KEY"],
    api_secret=os.environ["SHOPLY_STORE_OWNER_API_SECRETE"],
) as shoply:
    session_response = shoply.list_sessions(limit=40)
 
for conversation in session_response.data:
    print(conversation.customer_id, conversation.user_questions)

توفر الحزمة أيضًا دوالًا للتحليلات، وأعداد النشاط، والمخططات الزمنية الكاملة للجلسات، والمنطقة الزمنية للمتجر، وإدارة المعرفة. راجع دليل حالات استخدام الأعمال  ومرجع API .

حزمة Node.js وTypeScript

يوفر مستودع shoply-merchant-api-js حزمة @shoplyai/merchant-api لـ Node.js 20 أو أحدث. وهي حزمة ESM تحتوي على تعريفات TypeScript مدمجة ولا تتضمن أي تبعيات وقت تشغيل. ثبّت الإصدار المثبت 2.1.3 مباشرة من GitHub:

npm install "github:shoplyai-public/shoply-merchant-api-js#v2.1.3"

استرجع أحدث الجلسات نفسها من خادم Node.js:

import { ShoplyMerchantClient } from "@shoplyai/merchant-api";
 
const storeKey = process.env.SHOPLY_STORE_KEY;
const apiSecret = process.env.SHOPLY_STORE_OWNER_API_SECRETE;
if (!storeKey || !apiSecret) {
  throw new Error("SHOPLY_STORE_KEY and SHOPLY_STORE_OWNER_API_SECRETE are required");
}
 
const shoply = new ShoplyMerchantClient({
  storeKey,
  apiSecret,
});
 
const sessionResponse = await shoply.listSessions({ limit: 40 });
 
for (const conversation of sessionResponse.data) {
  console.log(conversation.customer_id, conversation.user_questions);
}

تغطي حزمة npm نقاط نهاية Merchant API نفسها التي تغطيها حزمة Python. راجع دليل حالات استخدام الأعمال  ومرجع API .

كلتا الحزمتين مخصصتان لخدمات الخلفية الموثوقة، والمهام المجدولة، والأدوات الداخلية الخاصة. لا تستورد أيًا من الحزمتين في شيفرة واجهة المتجر ولا تكشف سر API داخل حزمة المتصفح.

هل يمكنني استدعاء HTTP API بدون حزمة؟

نعم. تظل Merchant API واجهة HTTPS قياسية. تستخدم أمثلة Python منخفضة المستوى أدناه مكتبة Requests حتى تتمكن من رؤية عقد الاتصال الكامل أو التكامل من لغة أخرى.

ثبّت Requests إذا لم تكن بيئتك تتضمنها بالفعل:

python -m pip install requests

تضيف الدالة المساعدة أدناه مفتاح المتجر وترويسة المصادقة إلى كل طلب:

import json
import os
from typing import Any
 
import requests
 
BASE_URL = "https://api.shoplyai.ai"
STORE_KEY = os.environ["SHOPLY_STORE_KEY"]
STORE_OWNER_API_SECRETE = os.environ["SHOPLY_STORE_OWNER_API_SECRETE"]
 
session = requests.Session()
session.headers.update({
    "Authorization": json.dumps({
        "store_key": STORE_KEY,
        "store_owner_api_secrete": STORE_OWNER_API_SECRETE,
    })
})
 
 
def shoply_get(api_name: str, **params: Any) -> dict[str, Any]:
    """Call one store-scoped Shoply API and surface HTTP or API-level errors."""
    response = session.get(
        f"{BASE_URL}/{api_name}",
        params={"store_key": STORE_KEY, **params},
        timeout=30,
    )
    response.raise_for_status()
 
    payload = response.json()
    if payload.get("error") is not None or payload.get("statusCode") not in (None, 200):
        raise RuntimeError(payload.get("error", "Shoply API request failed"))
    return payload
 
 
def shoply_post(
    api_name: str,
    payload: dict[str, Any] | None = None,
    **params: Any,
) -> dict[str, Any]:
    """Write store-scoped data and surface HTTP or API-level errors."""
    response = session.post(
        f"{BASE_URL}/{api_name}",
        params={"store_key": STORE_KEY, **params},
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
 
    result = response.json()
    if result.get("error") is not None or result.get("statusCode") not in (None, 200):
        raise RuntimeError(result.get("error", "Shoply API request failed"))
    return result

تستخدم الأمثلة أدناه هذا العميل المشترك. تضيف كلتا الدالتين المساعدتين مفتاح المتجر الموثق تلقائيًا.

هل يمكنني إدارة معرفة Shoply AI عبر API؟

نعم. يستخدم admin_store_knowledge طريقة GET لاسترجاع المعرفة وطريقة POST لإنشائها أو تحديثها أو حذفها أو إعادة الزحف إليها. أي طلب POST يستخدم معرّف معرفة موجودًا سيقوم بتحديث ذلك الإدخال؛ أما استخدام معرّف جديد فيؤدي إلى إنشاء واحد جديد.

قبل أتمتة التحديثات، خطط لمعرفة متجر مفيدة باستخدام الأمثلة الواردة في دليل التدريب الخاص بنا.

يمكن لعمليات كتابة المعرفة أن تغيّر الإجابات المعروضة للمتسوقين. استخدم سرًا مخصصًا للنظام الذي يدير المعرفة، وتحقق من صحة المحتوى قبل إرساله، ولا تكشف أبدًا بيانات الاعتماد هذه القادرة على الكتابة داخل JavaScript الخاص بواجهة المتجر.

عرض المعرفة الحالية

knowledge_payload = shoply_get(
    "admin_store_knowledge",
    knowledge_id_to_retrieve="_ALL_",
)
 
for knowledge_id, knowledge in knowledge_payload["data"].items():
    print(knowledge_id, knowledge.get("title"))

نموذج استجابة

{
  "data": {
    "knowledge::shipping-policy": {
      "title": "Shipping policy",
      "text": "Orders leave our warehouse within two business days.",
      "epoch_edit": 1787211246
    }
  }
}

إنشاء أو تحديث معرفة نصية مخصصة

اختر معرّف معرفة ثابتًا وفريدًا. أعد استخدام المعرّف نفسه عند تحديث ذلك الإدخال.

from time import time
 
knowledge_id = "knowledge::shipping-policy"
result = shoply_post(
    "admin_store_knowledge",
    {
        knowledge_id: {
            "title": "Shipping policy",
            "text": (
                "Orders leave our warehouse within two business days. "
                "Standard delivery normally takes three to five business days."
            ),
            "epoch_edit": int(time()),
        }
    },
)
 
print(result)

نموذج استجابة

{
  "statusCode": 200
}

تعني الاستجابة الناجحة أنه تم حفظ المعرفة. قد تستغرق فهرسة البحث بضع دقائق، لذلك قد لا تظهر الإجابة الجديدة فورًا. إذا أفاد API بأنه تم حفظ المحتوى لكن الفهرسة متأخرة، فأكد الإدخال المخزن باستخدام GET قبل إعادة محاولة الكتابة.

إضافة صفحة ويب خارجية

استخدم معرّفًا يبدأ بـ external_url::. ضع عنوان URL الكامل http:// أو https:// داخل text.

from time import time
 
result = shoply_post(
    "admin_store_knowledge",
    {
        "external_url::returns-policy": {
            "title": "Returns and exchanges",
            "text": "https://www.example.com/policies/returns",
            "epoch_edit": int(time()),
        }
    },
)

رفع ملف معرفة وتسجيله

يجب أن تكون ملفات المعرفة بصيغة PDF أو TXT أو Markdown وأن يكون حجمها أقل من 5 ميغابايت. ارفع الملف أولًا، ثم احفظ موقع S3 الخاص المعاد كإدخال معرفة.

from pathlib import Path
from time import time
 
file_path = Path("shipping-policy.md")
with file_path.open("rb") as file_handle:
    upload_response = session.post(
        f"{BASE_URL}/user_generated_file",
        params={"store_key": STORE_KEY, "folder": "knowledge_file"},
        files={"file": (file_path.name, file_handle, "text/markdown")},
        timeout=60,
    )
 
upload_response.raise_for_status()
uploaded = upload_response.json()
if uploaded.get("statusCode") != 200:
    raise RuntimeError(uploaded.get("error", "Knowledge file upload failed"))
 
shoply_post(
    "admin_store_knowledge",
    {
        "knowledge_file::shipping-policy": {
            "title": "Shipping policy document",
            "text": uploaded["file_url"],
            "epoch_edit": int(time()),
        }
    },
)

نموذج استجابة الرفع

{
  "message": "File uploaded successfully",
  "statusCode": 200,
  "file_url": "s3://shoplystores/your-store.myshopify.com/uploads/shipping-policy.md"
}

تعامل مع file_url على أنه موقع خاص غير شفاف تعيده Shoply. لا تقم بإنشائه أو تغييره بنفسك.

حذف المعرفة

الحذف دائم. استرجع الإدخالات الحالية أولًا وأرسل فقط المعرّفات الدقيقة التي تنوي إزالتها.

result = shoply_post(
    "admin_store_knowledge",
    {
        "knowledge_ids_to_delete": [
            "knowledge::shipping-policy",
            "external_url::returns-policy",
            "knowledge_file::shipping-policy",
        ]
    },
)

طلب إعادة زحف للموقع الإلكتروني

استخدم إعادة الزحف بعد تغيّر المحتوى على موقع التاجر الإلكتروني. لا يكون ذلك ضروريًا عادة بعد كل تحديث لنص مخصص.

result = shoply_post(
    "admin_store_knowledge",
    re_crawl_ind="true",
)

حالات استخدام الأعمال

• مزامنة إرشادات الشحن، والإرجاع، والضمان، والمقاسات، أو العناية بالمنتج من نظام محتوى داخلي.
• نشر معلومات مؤقتة خاصة بالحملات أو العطلات دون نسخها يدويًا إلى Shoply Admin.
• إضافة صفحة سياسة أو مستند معتمد إلى قاعدة المعرفة كجزء من سير عمل النشر.
• إزالة الإرشادات القديمة فور انتهاء سياسة أو عرض ترويجي.

أمثلة على Merchant API

1. استرجاع تحليلات الأداء

يقوم admin_store_analytics بتشغيل جدول Analytics → Summary. وهو يعيد الجلسات، والمحادثات، وعمليات البحث، والنقرات، وأحداث الإضافة إلى السلة، وعمليات الشراء، والإيرادات المنسوبة.

نقطة النهاية

GET https://api.shoplyai.ai/admin_store_analytics

معلمات الاستعلام

تستخدم التقارير الشهرية السجل الشهري المخزن في Shoply ولا تتطلب حدودًا للتاريخ.

مثال Python

daily_report = shoply_get(
    "admin_store_analytics",
    report_type="daily",
    start_date="20260801",
    end_date="20260820",
)
 
for row in daily_report["data"]:
    print(row["date"], row["sessions"], row["purchases"], row["revenue"])
 
print("Totals:", daily_report["totals"])
 
# Weekly rows use the Monday of each week as their date label.
weekly_report = shoply_get(
    "admin_store_analytics",
    report_type="weekly",
    start_date="20260701",
    end_date="20260820",
)
 
# Monthly requests do not need start_date or end_date.
monthly_report = shoply_get("admin_store_analytics", report_type="monthly")

نموذج استجابة

{
  "data": [
    {
      "date": "20260820",
      "sessions": 42,
      "chats": 18,
      "searches": 24,
      "clicks": 11,
      "add_to_cart": 5,
      "purchases": 2,
      "revenue": "$168.00",
      "revenue_usd": "$168.00"
    }
  ],
  "totals": {
    "date": "totals",
    "sessions": 42,
    "chats": 18,
    "searches": 24,
    "clicks": 11,
    "add_to_cart": 5,
    "purchases": 2,
    "revenue": "$168.00",
    "revenue_usd": "$168.00"
  },
  "report_type": "daily"
}

يمكن أن تحتوي الإيرادات على أكثر من عملة واحدة. تعامل مع revenue كنص للعرض. استخدم revenue_usd عندما تحتاج إلى القيمة الموحّدة بالدولار الأمريكي التي يعرضها Shoply.

حالات استخدام الأعمال

• إرسال ملخص يومي لتأثير المبيعات إلى التاجر أو فريق التجارة الإلكترونية.
• مقارنة عمليات البحث ونقرات المنتجات وأحداث الإضافة إلى السلة وعمليات الشراء لاكتشاف نقاط التراجع في القمع الشرائي.
• تزويد لوحة معلومات أسبوعية أو شهرية لذكاء الأعمال دون استخراج البيانات من صفحة Shoply Admin.
• تتبع الإيرادات المنسوبة بمرور الوقت ومقارنتها مع تغييرات الترويج التجاري أو الحملات.

2. استرجاع المنطقة الزمنية للمتجر

يوفر admin_get_store_metadata شارة المنطقة الزمنية المعروضة في Analytics → Chat & Search History. تستخدمها الصفحة لترجمة نشاط UTC إلى التوقيت المحلي للمتجر.

نقطة النهاية

GET https://api.shoplyai.ai/admin_get_store_metadata

معلمات الاستعلام

مثال Python

timezone_payload = shoply_get(
    "admin_get_store_metadata",
    metadata_key="time_zone",
)
 
timezone = timezone_payload["data"]
print(timezone["ianaTimezone"], timezone["timezoneOffsetMinutes"])

نموذج استجابة

{
  "data": {
    "ianaTimezone": "America/Los_Angeles",
    "timezoneOffset": -7,
    "timezoneOffsetMinutes": -420
  },
  "statusCode": 200
}

حالات استخدام الأعمال

• تجميع نشاط UTC ضمن الأيام التقويمية المحلية نفسها التي يراها التاجر في Analytics.
• جدولة عمليات التصدير اليومية بعد انتهاء اليوم المحلي للمتجر.
• تسمية التقارير بمنطقة زمنية IANA واضحة مثل America/Los_Angeles.

يمكن أن تتغير إزاحات المنطقة الزمنية بسبب قواعد التوقيت الصيفي. فضّل ianaTimezone عندما يدعم نظام التقارير لديك ذلك بدلًا من حفظ إزاحة رقمية واحدة بشكل دائم.

3. استرجاع أعداد النشاط

يعيد query_api_usage_count نشاط المتجر مجمعًا حسب تاريخ UTC أو حسب دقيقة UTC الأصلية. كما أنه المصدر للمخطط البياني للنشاط في Analytics → Chat & Search History.

نقطة النهاية

GET https://api.shoplyai.ai/query_api_usage_count

معلمات الاستعلام

مثال Python

activity = shoply_get(
    "query_api_usage_count",
    start_dt_utc="2026-08-01 00:00:00",
    end_dt_utc="2026-08-20 23:59:59",
    groupby="utc_date",
)
 
for row in activity["data"]:
    print(row)

نموذج استجابة

{
  "data": [
    {
      "utc_date": "2026-08-20",
      "QA": 18,
      "CHAT": 18,
      "SEARCH": 20,
      "CACHED_SEARCH": 4,
      "PRODUCT_SEARCH": 22,
      "CLICK": 11,
      "ADD_TO_CART": 5,
      "CHECKOUT": 2
    }
  ]
}

تتضمن الصفوف عدادات النشاط المتاحة لتلك الفترة، مثل أسئلة الدردشة، وعمليات البحث، والنقرات، وأحداث الإضافة إلى السلة، وأحداث إتمام الشراء. قد تغيب العدادات التي لا تحتوي على نشاط بدلًا من تعيينها إلى الصفر.

حالات استخدام الأعمال

• إنشاء مخطط نشاط كل ساعة أو كل يوم مشابه لذلك الموجود في Chat & Search History.
• اكتشاف الارتفاعات غير المعتادة في الزيارات أو الانخفاضات المفاجئة في تفاعل العملاء.
• مقارنة حجم البحث عن المنتجات مع النقرات، وأحداث الإضافة إلى السلة، وعمليات إتمام الشراء.
• تقدير الأوقات التي ينبغي فيها لفرق الدعم والترويج التجاري مراجعة أكثر الفترات ازدحامًا.

4. استرجاع ملخصات جلسات الدردشة والبحث

يعيد query_sessionized_chat سجلًا مضغوطًا واحدًا لكل جلسة عميل. كما أنه يشغّل قائمة الجلسات في Analytics → Chat & Search History.

نقطة النهاية

GET https://api.shoplyai.ai/query_sessionized_chat

معلمات الاستعلام

استرجاع أحدث 40 جلسة

summary_payload = shoply_get(
    "query_sessionized_chat",
    start_dt_utc="undefined",
    end_dt_utc="undefined",
    num_sessions=40,
    ScanIndexForward="false",
)
 
sessions = summary_payload["data"]
for conversation in sessions:
    print(conversation["customer_id"], conversation.get("user_questions", ""))

استرجاع الجلسات ضمن نطاق UTC

summary_payload = shoply_get(
    "query_sessionized_chat",
    start_dt_utc="2026-08-20 00:00:00",
    end_dt_utc="2026-08-20 23:59:59",
    ScanIndexForward="false",
)

عندما يكون حدا الوقت موجودين معًا، يعيد API الجلسات ضمن النطاق الكامل؛ ولا يقيّد num_sessions هذا الاستعلام المحدد بحدود.

نموذج استجابة

{
  "data": [
    {
      "customer_id": "customer-or-session-id",
      "user_questions": "Do you have this in blue?\nWhen will it ship?",
      "start_timestamp_ms": 1787184000000,
      "end_timestamp_ms": 1787184065000,
      "session_types": "product information, click",
      "customer_email": null,
      "customer_info": {},
      "sentiment": "positive",
      "num_questions": 2,
      "num_searches": 1,
      "num_clicks": 1
    }
  ]
}

تختلف الحقول الاختيارية حسب الجلسة. احتفظ بـ customer_id وstart_timestamp_ms وend_timestamp_ms إذا كنت تخطط لاسترجاع المخطط الزمني الكامل.

حالات استخدام الأعمال

• مراجعة عينة من المحادثات الحديثة من أجل جودة الإجابات وتدريب الدعم.
• العثور على أسئلة العملاء المتكررة التي ينبغي أن تؤثر في نصوص المنتجات أو الأسئلة الشائعة.
• تحديد الجلسات عالية النية التي تحتوي على عمليات بحث أو نقرات على المنتجات أو إجراءات تسوق أخرى.
• تصدير صف واحد لكل جلسة لتحليل الاتجاهات مع تجنب الحمولة الأكبر على مستوى الأحداث.

5. استرجاع جلسة كاملة واحدة

مرر ملخصًا محددًا إلى query_log_visualization لاسترجاع أحداث العميل، والذكاء الاصطناعي، والبحث، والتجارة الخاصة به.

نقطة النهاية

GET https://api.shoplyai.ai/query_log_visualization

معلمات الاستعلام

مثال Python

from datetime import datetime, timezone
 
 
def utc_from_milliseconds(timestamp_ms: int) -> str:
    """Format a Shoply millisecond timestamp for the history API."""
    value = datetime.fromtimestamp(timestamp_ms / 1000, tz=timezone.utc)
    return value.strftime("%Y-%m-%d %H:%M:%S")
 
 
selected = sessions[0]
timeline_payload = shoply_get(
    "query_log_visualization",
    date_time_utc_start=utc_from_milliseconds(selected["start_timestamp_ms"]),
    date_time_utc_end=utc_from_milliseconds(selected["end_timestamp_ms"]),
    session_id=selected["customer_id"],
    start_timestamp_ms=selected["start_timestamp_ms"],
)
 
for event in timeline_payload["data"]:
    print(event.get("server_timestamp_ms"), event.get("action_type"))

نموذج استجابة

{
  "data": [
    {
      "action_type": "QA",
      "session_id": "customer-or-session-id",
      "utc_date_time": "2026-08-20 00:00:00",
      "start_timestamp_ms": 1787184000000,
      "server_timestamp_ms": 1787184000123,
      "Q": {
        "question": "Do you have this in blue?",
        "question_context": {}
      },
      "task_id": "task-id",
      "list_tokens": [
        {
          "data_type": "LLMOutput",
          "data": "Yes. These blue options are currently available."
        }
      ],
      "dict_search_results": {}
    }
  ]
}

يمكن أن يحتوي المخطط الزمني على أسئلة العملاء، وإجابات الذكاء الاصطناعي، ونتائج البحث، ونقرات المنتجات، وأحداث الإضافة إلى السلة، وأحداث إتمام الشراء، ومشاركة الوكيل البشري. استخدم server_timestamp_ms لترتيب أنواع الأحداث المختلطة. قد تحتوي السجلات الأقدم على عدد أقل من الحقول.

حالات استخدام الأعمال

• تدقيق ما الذي سأله العميل بالضبط وما الذي أجاب به Shoply أثناء تحقيق متعلق بالدعم.
• مراجعة جودة الإجابات جنبًا إلى جنب مع نتائج البحث والمنتجات المعروضة للمتسوق.
• إعادة بناء الرحلة من السؤال إلى النقر أو الإضافة إلى السلة أو إتمام الشراء.
• تشخيص جلسة واحدة أبلغ عنها عميل دون البحث في سجل غير ذي صلة.

هل يمكنني استخدام سر واحد لكل API؟

نعم. إن store_owner_api_secrete الصالح يكون محصورًا في متجر واحد ويعمل عبر نقاط نهاية Merchant API المذكورة أعلاه. وبالنسبة إلى حسابات SiteChat، فإن السر نفسه يصادق أيضًا على واجهات API الخاصة برفع الكتالوج. ولتشغيل أكثر أمانًا، استخدم أسرارًا مسماة منفصلة لأنظمة منفصلة — على سبيل المثال، واحد لتصدير البيانات الليلي وآخر للوحة معلومات داخلية.

إذا تم إيقاف أحد التكاملات أو تعرّض للاختراق، فألغِ سرّه فقط من Shoply Settings. وستستمر التكاملات الأخرى في العمل.

ما الذي ينبغي أن أعرفه عن الانتهاء، والخصوصية، والأخطاء؟

راجع أيضًا مصادر بيانات Shoply والخصوصية لفهم المعلومات المتاحة لإجابات العملاء.

• تنتهي صلاحية أسرار API الخاصة بمالك المتجر بعد 90 يومًا. أنشئ بديلًا وحدّث التكامل قبل تاريخ انتهاء صلاحيته.
• إن فترة الاحتفاظ القياسية لدى Shoply بسجل الدردشة والبحث هي أيضًا 90 يومًا. انتهاء صلاحية السر والاحتفاظ بالبيانات سياستان منفصلتان.
• قد تحتوي استجابات السجل على بيانات شخصية، بما في ذلك معرّفات العملاء، وعناوين البريد الإلكتروني، والموقع التقريبي، والأسئلة، ونشاط التسوق. خزّنها وعالجها وفقًا لسياسة الخصوصية الخاصة بك والقانون المعمول به.
• يعني HTTP 403 أن السر مفقود أو غير صالح أو منتهي الصلاحية أو مُلغى أو تابع لمتجر مختلف.
• يعني HTTP 422 عادة أن معلمة استعلام مطلوبة مفقودة أو تحمل اسمًا خاطئًا.
• يعني HTTP 500 أو استجابة تحتوي على statusCode: 500 أن الطلب وصل إلى Shoply لكن لم يمكن إكماله. أعد محاولة الإخفاقات المؤقتة باستخدام backoff وتواصل معنا إذا استمر الخطأ.
• استخدم نطاقات UTC محددة بوضوح لعمليات التصدير والمهام المتكررة حتى تبقى الاستجابات قابلة للإدارة.

هل يُعد بحث المنتجات جزءًا من Merchant API؟

تمتلك واجهة البحث العامة عن المنتجات في Shoply مصادقة وعقد طلب مختلفين. راجع كيفية الوصول إلى Shoply AI Search عبر API إذا كنت تريد نتائج بحث المنتجات لتجربة موجهة للمتسوقين بدلًا من بيانات التاجر الخاصة.

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

نعم. يمكن لحسابات SiteChat رفع المنتجات المنظمة وصور المنتجات باستخدام سر API الخاص بمالك المتجر نفسه. وقد تم توثيق نقاط نهاية الكتالوج تلك بشكل منفصل في كيفية رفع الكتالوج الخاص بك لـ SiteChat. أما متاجر Shopify فتستمر في مزامنة المنتجات عبر Shopify ولا تستخدم مسارات الرفع تلك.

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