البدء للمطورين

يتيح لك زيتون استخدام الواجهة البرمجية API، للبدء بذلك اتبع الخطوات التالية:

تسجيل الدخول إلى لوحة التحكم

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

الحصول على مفتاح API

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

تظهر صفحة إعدادات الحساب، نتأكد من تفعيل خيار توليد مفاتيح الواجهة البرمجية API key، ثم نضغط على زر توليد للحصول على المفتاح كما هو موضح في الصورة التالية:

ننسخ المفتاح الناتج كما هو موضح في الصورة التالية:

نحتفظ بالمفتاح في مكان آمن ثم نضغط على زر حفظ.

الوصول للواجهة البرمجية

للإتصال مع API زيتون يجب إرسال طلبات HTTP إلى عنوان الأساس (Base URL) الخاص بمركز المساعدة لديك:

https://your-domain.com/api/agent/v1/

استبدل your-domain.com بنطاق مركز المساعدة الخاص بك.

كما أن الطلبات تتطلب تمرير مفتاح API ضمن ترويسة الطلب (Header) باستخدام صيغة Bearer Token:

Authorization: Bearer YOUR_API_KEY

كذلك عند إرسال بيانات إلى الخادم (مثل POST أو PUT أو PATCH) يجب تحديد:

Content-Type: application/json

البدء بإرسال الطلبات

يُمكنك البدء حالياً بإرسال الطلبات، على سبيل المثال لإرسال طلب GET بإستخدام curl لعرض صناديق البريد نُرسل الطلب التالي:

curl "https://example.com/api/agent/v1/inboxes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

كذلك يُمكنك إرسال طلبات POST ، على سبيل المثال لإنشاء فريق جديد باسم "فريق المبيعات" ضمن مركز المساعدة نُرسل الطلب التالي:

curl "https://example.com/api/agent/v1/teams" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "فريق المبيعات",
    "status": "active",
    "description": "فريق مسؤول عن الأمور المتعلقة ببيع المنتجات بالشركة",
    "permissions": ["contact", "company"],
    "inbox_ids": [1010]
  }'

ملاحظات

• مهم أن ننتبه لصحة كتابة معاملات الاستعلام، فأي خطأ إملائي كتبديل قيمة المعامل active إلى Active يعني أن الواجهة لن تعطينا الاستجابة المطلوبة
• يُمكن إرسال مختلف أنواع طلبات HTTP الأخرى مثل PUT أو PATCH أو DELETE
• يُمكن إستخدام curl أو لغات برمجة مثل بايثون أو Node.js أو روبي أو جافا أو PHP