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

محتويات الصفحة

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

    المتطلبات الأساسية

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

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

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

    Authorization: Bearer YOUR_API_KEY

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

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

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

    نحتفظ به في مكان آمن، ثم نضغط زر حفظ.

    أنواع طلبات HTTP

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

    GET

    لعرض بيانات مركز المساعدة

    POST

    لإضافة بيانات جديدة لمركز مساعدة

    PUT

    لتعديل شامل للبيانات في مركز المساعدة

    PATCH

    لتعديل جزئي للبيانات في مركز المساعدة

    DELETE

    لحذف بيانات في مركز المساعدة

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

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

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

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

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

    2xx

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

    400

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

    401

    مشكلة في الاستيثاق، بسبب مفتاح API غير صحيح أو رمز وصول TOKEN غير صحيح أو بيانات دخول غير صحيحة.

    402

    فشل الطلب رغم صحة المعاملات المُقدمة لسبب ما كخطأ داخلي في الخادم، أو وجود مشكلة في الاتصال.

    403

    الطلب صحيح لكن الوكيل لا يملك صلاحية للوصول له وتنفيذه.

    404

    لا يمكن الوصول للمورد المطلوب، بسبب استخدام عنوان URL خاطئ، أو نقله أو حذفه.

    409

    وجود تعارض بين الطلب المرسل وطلب آخر قيد المعالجة، كمحاولة تغيير نفس البيانات بنفس اللحظة.

    429

    إرسال عدد طلبات كثيرة جدًا إلى الواجهة خلال فترة زمنية معينة.

    5xx

    وجود خطأ ما في الخادم نفسه أو في طريقة معالجة الطلبات ولا علاقة له بالطلب المرسل للواجهة البرمجية، وهي أخطاء مؤقتة ونادرة الحدوث.

    محتويات الصفحة