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

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

متطلبات الاتصال

يتطلب الاتصال بالواجهة البرمجية لزيتون الأمور التالية:

حساب وكيل

نحتاج لحساب وكيل agent مسجّل في مركز المساعدة، ويملك صلاحية الوصول للبيانات المطلوبة كالإعدادات، وجهات الاتصال، والدردشة المباشرة، وقاعدة المعرفة. وتجدر الإشارة إلى أن وكيل مركز المساعدة سيحصل على صلاحياته من فريق العمل team الذي ينتمي إليه.

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

نحتاج للحصول على مفتاح الواجهة البرمجية API Key وتمريره ضمن ترويسة الطلب، من أجل الاستيثاق من هوية الوكيل منفّذ الطلب ومنحه الوصول.

توفر الواجهة البرمجية لزيتون مفتاح من نوع Bearer Token يمرر على النحو التالي:

Authorization: Bearer YOUR_API_KEY

الحصول على مفتاح الواجهة البرمجية

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

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

أنواع طلبات HTTP

يمكن التخاطب مع واجهة زيتون البرمجية باستخدام طلبات HTTP القياسية وهي:

GET	لعرض بيانات من مركز المساعدة
POST	لإضافة بيانات جديدة لمركز المساعدة
PUT	لتعديل بيانات أو إعدادات في مركز المساعدة
DELETE	لحذف بيانات من مركز المساعدة

عنوان الواجهة البرمجية

تبدأ جميع الطلبات المرسلة للواجهة البرمجية بعنوان URL الرئيسي التالي:

{protocol}://{subdomain}.zaetoon.com/api/agent/{version}

نستبدل {protocol} بالبروتوكول الافتراضي للتخاطب مع واجهة زيتون البرمجية https
نستبدل {subdomain} باسم نطاق مركز المساعدة الخاص بنا
نستبدل {version} برقم إصدار واجهة زيتون البرمجية، وهو حاليًا v1

عنوان عرض صناديق البريد

لعرض كافة صناديق البريد inboxes ضمن مركز مساعدة له النطاق example.com، نرسل طلب GET للعنوان التالي:

example.com/api/agent/v1/inboxes

عنوان إضافة شخص لجهات الاتصال

لإضافة شخص contact لجهات الاتصال ضمن مركز مساعدة يملك النطاق example.com، سنرسل طلب POST للعنوان التالي:

example.com/api/agent/v1/contacts

عنوان تعديل صلاحيات فريق عمل

لتعديل صلاحيات فريق عمل ضمن مركز مساعدة له النطاق example.com، نرسل طلب PUT مع تمرير الرقم التعريفي للفريق المطلوب كمعامل مسار كالتالي:

example.com/api/agent/v1/teams/{id}