دليل الربط

اربط المساعد رفيق بموقعك عبر قناتين: مزامنة المحتوى، وتضمين الودجت بسطرٍ واحد.

نظرة عامة

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

المفاتيح

لكل حسابٍ زوج مفاتيح من لوحة التحكم، قسم «مفاتيح API»:

• pk_live_… — عام، يوضع في الودجت لتحديد الهوية.
• sk_live_… — سرّي، لواجهة المزامنة من خادمك حصرًا.

مزامنة المحتوى — رفع / تحديث

المفتاح هو external_id (معرّفك للعنصر): أول إرسالٍ ينشئ، والتالي بالمعرّف نفسه يحدّث. حتى ١٠٠ عنصرٍ في الطلب.

# الترويسة: Authorization: Bearer sk_live_xxx
curl -X POST https://agentrafeeq.com/api/v1/content/items:upsert \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "external_id": "product-1024",
      "type": "product",
      "title": "حذاء رياضي",
      "summary": "حذاء جريٍ خفيفٌ للمسافات الطويلة.",
      "url": "https://mystore.com/products/1024",
      "image_url": "https://mystore.com/img/1024.jpg",
      "price": 349.00,
      "currency": "SAR",
      "metadata": { "category": "أحذية" }
    }]
  }'

حذف عنصر

curl -X DELETE https://agentrafeeq.com/api/v1/content/items/product-1024 \
  -H "Authorization: Bearer sk_live_xxx"

يُحذف العنصر ومقاطعه فورًا، ويظهر أثر ذلك في البحث مباشرةً.

إعادة فهرسة كاملة

curl -X POST https://agentrafeeq.com/api/v1/content/reindex \
  -H "Authorization: Bearer sk_live_xxx"

تضمين الودجت

أضِف هذا السطر قبل </body> في أي صفحة:

<script async
  src="https://agentrafeeq.com/widget.js"
  data-bot-key="pk_live_xxx"></script>

يعمل الودجت داخل حاويةٍ معزولة (لا تتأثّر بستايلات موقعك)، ويجلب إعداداته تلقائيًا، وحجمه نحو ١٠ كيلوبايت مضغوطًا وغير متزامنٍ فلا يبطئ صفحتك.

قائمة النطاقات المسموحة

من لوحة التحكم، اربط كل مفتاحٍ عامٍّ بنطاقات موقعك؛ حينها يرفض الخادم أي طلبٍ من متصفّحٍ على نطاقٍ غير مُدرَج، فلا يمكن استخدام مفتاحك على موقعٍ آخر. اترك القائمة فارغةً في التجارب فقط.

الحدود والحصص

عند بلوغ الحد يردّ الخادم بالرمز 429 برسالةٍ لبقةٍ للزائر. ويحمي الودجت حدُّ معدّلٍ لكل مفتاحٍ ولكل عنوان IP.

مرجع الأخطاء

جميع ردود الأخطاء بصيغة JSON على الشكل: { "message": "…", "code": "…" }.