نظرة عامة على API

تتبع كل نقطة نهاية REST في RolChat عقدًا واحدًا: عنوان URL الأساسي نفسه، وغلاف الاستجابة نفسه، والترقيم نفسه، وشكل الأخطاء نفسه. تعلّمه مرة واحدة، وستُقرأ كل عائلة نقاط نهاية في مرجع نقاط النهاية بالطريقة نفسها.

عنوان URL الأساسي والإصدارات

https://api.rolchat.com/api/v1/

الإصدار جزء من المسار. إضافة حقول اختيارية أو نقاط نهاية جديدة أو معاملات استعلام جديدة بقيم افتراضية ليست تغييرًا كاسرًا ولا ترفع الإصدار. التغييرات الكاسرة تصدر كـ v2، ونقاط نهاية v1 الموقوفة تدريجيًا تظل تعمل لمدة ستة أشهر على الأقل بعد الإعلان عنها (راجع الإيقاف التدريجي).

المصادقة

الطريقة	الترويسة	الاستخدام
JWT bearer	Authorization: Bearer <access_token>	الجلسات التفاعلية (تطبيق الويب، وتطبيقات الجوال)
مفتاح API	Authorization: Bearer rcp_<secret>	الاستدعاءات بين الأنظمة، ومفاتيح API للإضافات
توقيع HMAC	X-RolChat-Signature: sha256=…	Webhooks الواردة من أنظمتك، راجع Webhooks
لا شيء	-	نقاط نهاية الويدجت العامة (/widget/…، /forms/…)، بنطاق الموقع والمصدر

للتكاملات استخدم مفتاح API (رمز وصول شخصي). تُنشأ المفاتيح في الإعدادات ← الإضافات ← مفاتيح RolChat API، وتُعرض مرة واحدة ولا تُخزَّن إلا كتجزئة. لا يستطيع المفتاح أبدًا فعل أكثر مما يستطيعه العضو الذي أنشأه: تُفحص نطاقاته مقابل الصلاحيات الحالية لذلك العضو في كل استدعاء. راجع المصادقة لمعرفة مدد صلاحية JWT، والترويسة X-Account-Id، والجلسات متعددة الشركات.

غلاف الاستجابة

مورد واحد:

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

قائمة:

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

الاستجابات بلا جسم (204 No Content بعد الحذف) تحمل مع ذلك الترويسة X-Request-Id.

خطأ:

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

code قيمة قابلة للقراءة آليًا بصيغة snake_case، وهي القيمة التي يُعتمد عليها في التفرّع؛ أما message فباللغة الإنجليزية ومخصصة للسجلات. يظهر field وdetails عندما يفيدان، ولا يحتويان أبدًا على بيانات شخصية. لا تُجيب API أبدًا بـ 200 مع مصفوفة errors: إذا وُجدت أخطاء فالحالة 400 أو أعلى. القائمة الكاملة للرموز في صفحة الأخطاء.

الترقيم

نقاط نهاية القوائم التي يمكن أن تكبر تستخدم الترقيم بالمؤشر. اطلب الصفحة الأولى بلا مؤشر، ثم أعد next_cursor الذي تلقيته كما هو حرفيًا:

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

• القيمة الافتراضية لـ limit هي 50 والحد الأقصى 200؛ والقيم الأكبر تُرفض بـ 400 validation_failed.
• المؤشرات معتمة وتنتهي صلاحيتها بعد 24 ساعة (400 validation_failed مع code: cursor_expired).
• النتائج متسقة مع اللقطة المأخوذة عند الصفحة الأولى: السجلات المحذوفة بين الصفحات تختفي، والسجلات الجديدة لا تظهر إلا عند البدء من جديد بلا مؤشر.
• تُرسل أيضًا ترويسة Link مع rel="next" وrel="prev" للعملاء الذين يفضّلونها.

عدم التكرار

أرسل الترويسة Idempotency-Key (UUID أو ULID، حتى 255 حرفًا) مع أي طلب POST أو PATCH أو DELETE:

• يُنفَّذ أول طلب بمفتاح ما، وتُخزَّن حالته وجسمه لمدة 24 ساعة.
• التكرار بالمفتاح نفسه وجسم الطلب نفسه يُعيد الاستجابة المخزّنة دون تنفيذ الآثار الجانبية مجددًا.
• التكرار بالمفتاح نفسه لكن بـ جسم مختلف يُرفض بـ 409 idempotency_key_conflict.

استخدمه لكل استدعاء يُنشئ شيئًا بآثار جانبية: إرسال رسالة أو بريد إلكتروني أو SMS، أو إجراء مكالمة، أو أي شيء يُحتسب ماليًا. طلبات GET عديمة التكرار دائمًا وتتجاهل الترويسة.

حدود المعدل

تُحتسب الحدود في الدقيقة وترتبط بالحساب أو بمفتاح API أو بالمستخدم (وبعنوان IP في المسارات التي لا تتطلب تسجيل الدخول). السقوف الافتراضية:

الفئة	الحد الافتراضي	في الدقيقة
الطلبات بلا تسجيل دخول (حسب IP)	60	لكل IP
مستخدم مسجَّل الدخول (لوحة التحكم)	1 000	لكل مستخدم
مفتاح API	1 000	لكل مفتاح
نقاط نهاية الويدجت العامة	60 لكل زائر، و600 لكل عنوان شبكة	في الدقيقة
تسجيل الدخول (/auth/login)	5	لكل IP
Webhooks الواردة	300	في الدقيقة
خادم MCP	600	في الدقيقة
نقاط نهاية OAuth	600	في الدقيقة

هذه السقوف هي الإعدادات الافتراضية للمنصة ويمكن للمشغّل تغييرها؛ ولا تضاعفها خطتك، وتُتفق حدود Enterprise في عقدك. تُعيد نقاط النهاية الخاضعة لحدود المعدل:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

عند تجاوز الحد تكون الاستجابة 429 مع code: rate_limited في المصفوفة errors وترويسة Retry-After بالثواني. انتظر هذه المدة قبل الاستدعاء التالي. عشر محاولات تسجيل دخول فاشلة تقفل الحساب لمدة 30 دقيقة.

الأحجام والمهل

الفئة	الحد الأقصى لجسم الطلب	مهلة الخادم
افتراضي	1 MB	30 ث
رسالة مع مرفقات	25 MB	30 ث
استيراد CSV	50 MB	يُعيد 202 ويعمل في الخلفية
صور قاعدة المعرفة	10 MB	30 ث
Bulk API	10 MB	30 ث
البحث	1 MB	10 ث
طلبات الذكاء الاصطناعي	1 MB	60 ث
نقاط نهاية الويدجت	100 KB	30 ث

الأجسام الزائدة عن الحد تحصل على 413 payload_too_large. الخدمة التي تتجاوز المهلة تُجيب بـ 504 مع code: upstream_timeout وتلميح retry_after عندما تفيد إعادة المحاولة.

أنواع المحتوى والتواريخ والمعرّفات

• الطلبات والاستجابات بصيغة application/json; charset=utf-8. رفع الملفات يستخدم multipart/form-data؛ وتصدير CSV يُعيد text/csv. يُرفض UTF-8 غير الصالح بـ 400 validation_failed.
• الطوابع الزمنية بصيغة ISO-8601 بتوقيت UTC وبدقة الملّي ثانية: 2026-04-20T14:23:45.123Z. يُقبل أي فرق توقيت ISO-8601 في المدخلات ويُوحَّد إلى UTC.
• المعرّفات قيم ULID أو UUID معتمة. لا توجد معرّفات رقمية، ولا تظهر عناوين البريد الإلكتروني أو أرقام الهواتف في URL أبدًا.

عزل المستأجرين والصلاحيات

كل طلب مصادَق عليه يعمل داخل حساب واحد. المورد الذي يتبع حسابًا آخر، أو موقعًا لا يشمله دور المستدعي، يُجاب عنه بـ 404 not_found بدلًا من 403، كي لا يُكشف وجود السجلات أبدًا. الرمز الصالح الذي يفتقر إلى الصلاحية المطلوبة (مثل contacts.delete) يُجاب عنه بـ 403 forbidden. بعض الصلاحيات تحمل لاحقة نطاق (conversations.read:own، :team، :all) تضيّق ما تُعيده القائمة.

يقبل PATCH الحقول القابلة للكتابة فقط. id وaccount_id وcreated_at وupdated_at وحقول الحالة مثل resolved_at للقراءة فقط؛ وإرسال أي منها يُعيد 400 validation_failed مع details.forbidden_fields. تغييرات الحالة تمر عبر إجراءات مخصصة مثل POST /tickets/:id/resolve.

تُسجَّل كل عملية كتابة في سجل تدقيق الحساب.

ترويسات المراقبة

تحمل كل استجابة:

X-Request-Id: req_01HK…

سجّل X-Request-Id. إنه أول ما يطلبه الدعم.

CORS

مصدر لوحة التحكم في المتصفح هو https://app.rolchat.com. تسمح نقاط نهاية الويدجت العامة بأي مصدر، أو بالمصادر التي تتحقق منها لموقع ما فقط. الاستدعاءات بين الخوادم بمفتاح API لا تخضع لـ CORS.

الإيقاف التدريجي

1. يُعلن عن التغيير في سجل التغييرات، وتبدأ نقطة النهاية المتأثرة بإرسال Deprecation: true وترويسة Sunset بتاريخ الإزالة.
2. تظل نقاط النهاية العامة تعمل لمدة ستة أشهر على الأقل بعد الإعلان.
3. لا تحدث الإزالة إلا في إصدار رئيسي جديد. داخل v1 التغييرات إضافية فقط.

السلامة

تعرض كل خدمة /healthz (الحيوية) و/readyz (الجاهزية).