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

واجهة Cliento Pro هي الواجهة نفسها التي يستخدمها تطبيق الويب الخاص بالمنتج. لا توجد مجموعة «عامة» مختصرة ولا قاعدة بيانات منفصلة للتكامل: ما تستطيع الشاشة عرضه يستطيع رمز مُصرَّح له قراءته، وما تستطيع الشاشة تغييره يستطيع رمز مُصرَّح له تغييره.

استخدمها لمزامنة جهات الاتصال مع نظام آخر، أو لدفع الطلبات من متجر إلكتروني، أو لسحب الصفقات إلى مستودع بيانات لأغراض التقارير، أو لتشغيل أي سير عمل تشغّله الواجهة. أما الاتجاه المعاكس - أن تُبلَّغ بالتغيير بدل أن تسأل عنه - فاستخدم له الـ Webhooks.

كل الموارد تقع تحت جذر واحد مُصدَّر. الإصدار موجود في المسار، وهو المكان الوحيد الذي يظهر فيه؛ لا يوجد ترويسة إصدار ولا تفاوض عبر Accept.

https://<your-cliento-host>/api/v1

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

• HTTPS فقط. الرموز اعتمادات حاملة؛ والطلب غير المشفَّر يسرّبها.
• ‏`Authorization: Bearer <token>` على كل نقطة طرفية عدا التسجيل وتسجيل الدخول. راجع «المصادقة».
• ‏`Content-Type: application/json` لأي طلب له جسم. الأجسام كائنات JSON - لا form-encoding ولا مصفوفة مجرَّدة في المستوى الأعلى.
• ‏`Accept: application/json`. الاستجابات JSON، والأخطاء كذلك، بما فيها 401 و500.
• UTF-8 في كل مكان. العربية والفارسية والرموز التعبيرية تُخزَّن وتُعاد كما هي.

curl -sS https://your-host/api/v1/crm/contacts \
  -H "Authorization: Bearer ct_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

ثلاثة أشكال تغطي معظم النقاط الطرفية، ومعرفة أيّها أمامك تكفي لكتابة عميل.

{
  "id": 4182,
  "tenant_id": 17,
  "first_name": "Sara",
  "last_name": "Ahmadi",
  "email": "sara@example.com",
  "phone": "+989121234567",
  "company": "Horizon Real Estate",
  "title": "Managing partner",
  "owner_user_id": 5,
  "created_by_user_id": 5,
  "display_name": "Sara Ahmadi",
  "created_at": "2026-08-01T09:14:22",
  "updated_at": "2026-08-19T16:02:41"
}

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

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

تجري ثلاث عمليات فحص على كل نداء، بالترتيب. الإخفاق في أيّها رفض، لا نتيجة فارغة:

1. 1المصادقة - الرمز حيّ وغير منتهٍ وغير مُبطَل. وإلا 401.
2. 2الصلاحية - يحمل الرمز الرمزَ المحدَّد الذي تطلبه النقطة الطرفية، مثل crm.contacts.write لإنشاء جهة اتصال. وإلا 403.
3. 3رؤية السجل - داخل مساحة العمل، ترى بعض الأدوار سجلاتها أو سجلات فريقها فقط. السجلات خارج هذا النطاق لا تظهر في القوائم أصلًا، والوصول المباشر إليها يعطي 404.

يمكن تقييد *الحقول* المفردة أيضًا. من لا يملك crm.contacts.view_phone يستلم phone مُقنَّعًا - بالطول نفسه وبتبديل كل محرف - لا محذوفًا. اعرض القيمة المقنَّعة ولا تعاملها كحقل فارغ.

كل تغيير في الحالة يكتب حدثًا، سواء جاء من الواجهة أو من سير عمل أو من تكاملك أنت. ‏GET /events هو ذلك السجل، وعليه بُنيت الـ Webhooks - فيستطيع التكامل أن يطابق نفسه مع التاريخ ذاته الذي تعرضه شاشة التدقيق في مساحة العمل.

{
  "id": 91442,
  "tenant_id": 17,
  "user_id": 5,
  "entity_type": "contact",
  "entity_type_label": { "en": "Contact", "fa": "مخاطب", "ar": "جهة اتصال" },
  "entity_id": 4182,
  "event_type": "ContactCreated",
  "event_type_label": { "en": "Contact created", "fa": "مخاطب ایجاد شد", "ar": "تم إنشاء جهة الاتصال" },
  "source": "api",
  "metadata": { "email": "sara@example.com" },
  "occurred_at": "2026-08-19T16:02:41"
}

‏event_type وentity_type رموز آلية مستقرة - طابِق عليها. أما أزواج *_label فتحمل صياغة المنتج بلغاته الثلاث وهي للعرض فقط، وقد تُعاد صياغتها دون إشعار.

الـ API نفسه محايد لغويًا، وهذا عقد مقصود لا نقص:

• الأوقات بتوقيت UTC وبصيغة ISO-8601 دون لاحقة إزاحة (2026-08-19T16:02:41). العرض بالتقويم الهجري الشمسي أو الميلادي خيار كل مستخدم؛ أما صيغة النقل فلا تتغير.
• قوائم القيم رموز آلية (open، in_progress، ContactCreated). ترجِمها في عميلك ولا تطابق على النص المعروض.
• رسائل الأخطاء بالإنجليزية. هي نص تشخيصي للمطوِّر. عرِّبها انطلاقًا من رمز error المستقر، لا من الجملة.
• المحتوى الذي تخزّنه يُعاد حرفيًا، بالحرف الذي أرسلته.