وثائق التكامل

الإرفاق بالواجهة

لإدخال رمز مساعد الخدمة إلى موقع الويب الخاص بك، ما عليك سوى استخدام سطر واحد من الشفرة.

احصل على رمز التضمين

قم بتسجيل الدخول إلى لوحة تحكم العميل → إعدادات القناة → رمز التضمين، وقم بنسخ رمز التضمين الخاص بك:

<script>
  window.$aicrs = window.$aicrs || { q: [] };
</script>
<script async src="https://your-support-domain.com/widget/loader.js" data-wk="YOUR_WIDGET_KEY"></script>

لصق هذا الرمز قبل كل صفحة على موقع الويب الخاص بك </body>، سيتم عرض رمز المحادثة كفقاعة في الزاوية اليسرى من الصفحة، ويمكن للزوار البدء في الاستفسار عند النقر.

قائمة بياض المجال

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

إعادة تعيين widget_key

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

الأسئلة الشائعة

• هل لا يظهر الرمز؟ تحقق مما إذا كان المجال الحالي ضمن قائمة البياض، وما إذا كان widget_key متطابقًا مع لوحة التحكم، وما إذا كان الحساب في فترة الخدمة.
• هل يؤثر ذلك على سرعة موقع الويب؟ حجم محمل أقل من 1 كيلو بايت ويتم تحميله بشكل غير متزامن، ولا يعيق تحميل الصفحة الخاصة بك.

تحديد اتصال العضو

بعد تسجيل الدخول إلى موقعك الإلكتروني، يُنادى على دالة identify لتقديم معلومات العضو، وعندها سيُربط نظام الخدمة بالعضو المعين — ويتمكن المُدَوِّن من رؤية هوية العضو مباشرة، وسيتم دمج الزيارات من أجهزة متعددة كنفس الزائر.

طريقة الاستدعاء

بعد التأكد من تسجيل الدخول على الصفحة الخاصة بك:

$aicrs.identify({
  externalId: 'U10086',      // إلزامي، المعرف الوحيد للعضو في نظامك
  name: 'السيدة لي',             // اختياري، الاسم المعروض
  phone: '138****0000',      // اختياري
  email: 'user@example.com', // اختياري
  hash: 'التوقيع HMAC المُحسَب من الخلفية',  // إلزامي، منع التزوير
  custom: { vip: 'gold' }     // اختياري، حقول إضافية، تظهر للمُدَوِّن
})

خوارزمية التوقيع

يجب حساب hash من الخلفية الخاصة بك (لا يمكن أن تظهر مفتاح widget_secret في الكود الأمامي):

hash = النص الناتج بحروف صغيرة من HMAC-SHA256(widget_secret, externalId)

مفتاح widget_secret يُعثر عليه في لوحة التحكم → إعدادات القناة → رمز التضمين، ويُعاد تعيينه مع widget_key.

مثال على Node.js:

const crypto = require('crypto')
const hash = crypto.createHmac('sha256', WIDGET_SECRET).update(externalId).digest('hex')

نتائج التحقق

سيُظهر الزائر الذي تمرير توقيعه المُتحقق من على أنه "تم التحقق" من قبل المُدَوِّن؛ في حالة فشل التحقق، سيتم تجاهل استدعاء identify والحفاظ على الهوية المجهولة، ولا سيُسبب خطأ يُعيق الصفحة الخاصة بك.

إرسال أحداث Webhook

عند وقوع أحداث أعمال رئيسية، يرسل النظام رسالة JSON إلى عنوان URL الذي قمت بتحديده، مما يسهل عليك مزامنة بيانات الدعم إلى نظامك الخاص.

التكوين

الوحة التحكم للمتجر → البيانات والأنظمة → Webhook: أدخل URL الهدف (يجب أن يكون HTTPS) والرمز السري secret، واختر نوع الأحداث التي ترغب في الاشتراك بها. بعد الحفظ، يمكنك الضغط على "إرسال حدث اختباري" لإجراء التكامل الفوري.

تنسيق الطلب

كل إرسال هو طلب POST:

POST إلى URL الهدف الخاص بك
Content-Type: application/json
X-AICRS-Event: نوع الحدث
X-AICRS-Signature: HMAC-SHA256(secret, محتوى الطلب) بتنسيق سداسي عشري صغير

هيكل محتوى الطلب:

{
  "event": "message.created",
  "tenant_id": 129,
  "timestamp": 1784500000,
  "data": { "快照": "..." }
}

أنواع الأحداث

التحقق من التوقيع وإعادة المحاولة

بعد استلام الإرسال، يرجى حساب HMAC-SHA256 باستخدام الرمز السري من محتوى الطلب الأصلي، وقارن النتيجة مع X-AICRS-Signature. إذا لم تتطابق، يجب رفض الطلب.

إذا عادت واجهتك برمز حالة 2xx، يُعتبر الطلب ناجحًا؛ في حالة الفشل، سيتم إعادة المحاولة 3 مرات بفاصل زمني 1 دقيقة / 5 دقائق / 15 دقيقة. إذا فشلت جميع المحاولات، سيُعتبر الطلب فاشلاً، ويمكنك مراجعة سبب الفشل في سجل التسليم من واجهة الإدارة لإجراء التصحيح اليدوي.

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

API المفتوح تُستخدم لقراءة بيانات خدمة العملاء من نظامك وإنشاء تذاكر، مع عزلها حسب العميل.

التوثيق

اللوحة الإدارية للعميل → البيانات والأنظمة لإنشاء مفتاح API (على شكل ak_، يتم عرض النص الواضح مرة واحدة فقط عند الإنشاء، يرجى الحفاظ عليه بعناية؛ يُصبح المفتاح القديم غير سارٍ فور إعادة تعيينه).

يجب أن تحمل جميع الطلبات رأس الطلب التالي:

Authorization: Bearer ak_المفتاح_الخاص_بـك

التحكم في التردد

يمكن لكل مفتاح 120 طلبًا كحد أقصى في الدقيقة، والعودة إلى 429 إذا تجاوز ذلك.

قائمة واجهات API

مثال:

curl -H "Authorization: Bearer ak_xxx" \
  "https://نطاق_خدمة_العميل_الخاص_بك/api/open/v1/conversations?page=1"

التوضيحات

• جميع الاستجابات هي JSON، وواجهات القائمة تدعم معلمة page للطلبية.
• لا يُدعم الإصدار الحالي لإرسال رسالة إلى الزائر عبر API.
• عند تعطيل العميل أو انتهاء الخدمة، تُوقف واجهات API أيضًا.

مطابقة رموز الخطأ

تُرجع جميع واجهات API رسالة خطأ موحدة بتنسيق JSON:

{ "code": "رمز الخطأ", "message": "تنبيه باللغة الصينية" }

العلاقة بين رمز حالة HTTP ورمز الخطأ:

الإجراءات المقترحة:

• 401/403: تحقق من صلاحية المفتاح وحالة خدمة الحساب.
• 429: يُرجى إعادة المحاولة لاحقًا حسب Retry-After أو استراتيجية التراجع.
• 5xx: يمكن إعادة المحاولة بسلاسة للواجهات المتطابقة (Idempotent)؛ أما العمليات غير المتطابقة، يُرجى التحقق أولاً قبل إعادة المحاولة.

واجهات CRM المفتوحة

يتم قراءة وكتابة بيانات العملاء والفرص عبر واجهة برمجة التطبيقات المفتوحة (/api/open/v1، مفتاح Bearer ak_، يتم إنشاؤه في لوحة تحكم البائع "البيانات والنظام → API").

العملاء

قواعد التكرار تتوافق مع الخلفية: external_id > رقم الهاتف > البريد الإلكتروني، في حالة التكرار سيتم دمجه مع العميل الموجود بدلًا من إنشاء سجل جديد.

الحد من التكرار: 120 طلبًا لكل مفتاح في الدقيقة، وفي حالة التخطي سيتم عودة 429.

إشعارات الأحداث العميلة

تُستخدم قنوات Webhook الحالية لإرسال أحداث دورة حياة العميل (الاشتراك من "البيانات والأنظمة → Webhook" في لوحة تحكم البائع)، وتتطابق توقيعات الأحداث وآليات إعادة المحاولة مع تلك المستخدمة في أحداث الرسائل (HMAC-SHA256 في X-AICRS-Signature، وإعادة المحاولة بمنطق الانتظار الأسي).

صيغة الحمولة: {"event":"customer.created","data":{...كائن العميل...},"ts":1690000000}. يُعتبر الاستلام مؤكدًا عند استلام رمز 2xx، وفي حالة استلام رمز غير 2xx أو انتهاء المهلة يتم إعادة المحاولة وفقًا لسياسة الانتظار.