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

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

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

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

1. حساب وكيل

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

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

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

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

Authorization: Bearer YOUR_API_KEY

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

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

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

أنواع طلبات HTTP

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

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

تبدأ جميع الطلبات المرسلة للواجهة البرمجية بعنوان 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}

رموز الاستجابة

قد نحصل على استجابات HTTP مختلفة عند التعامل مع الواجهة البرمجية لزيتون

رموز النجاح 2xx

تشير الرموز 2xx إلى قبول الطلب الذي أرسله الوكيل ومعالجته بنجاح، على سبيل المثال يدل الرمز 200 على نجاح الطلبات من النوع GET، والرمز 201 على نجاح الطلبات من النوع POST.

رموز أخطاء جانب العميل 4xx

تشير الرموز 4xx لوجود خطأ في الطلب المرسل من قبل العميل، وقد يقع نتيجة عدة أسباب تتعلق ببنية الطلب نفسه، أو بمفتاح الواجهة البرمجية API Key.

ومن أهم رموز أخطاء 4xx:

رموز أخطاء جانب الخادم 5xx

تشير الرموز 5xx مثل 500 و 502 و 503 و 504 إلى وجود خطأ ما في الخادم نفسه أو في طريقة معالجة الطلبات ولا علاقة لها بالطلب المرسل للواجهة البرمجية، وهي أخطاء مؤقتة ونادرة الحدوث.