التعامل مع الوكلاء

نشرح في هذا المقال التعامل مع وكلاء مركز المساعدة كإنشاء وكيل جديد، أو عرض بيانات الوكلاء أو تعديل بياناته أو حذفه من خلال الواجهات البرمجية لزيتون من خلال عدة أمثلة عملية.

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

export TOKEN="YOUR_API_KEY" 

طلب إنشاء وكيل

يمكنك إنشاء وكيل agent جديد في مركز المساعدة الذي تديره بإرسال طلب من نوع POST إلى نقطة الوصول Create an agent مع إرسال بيانات الوكيل في جسم الطلب.

إنشاء وكيل جديد

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

curl -X POST \
  --header 'Authorization: Bearer @TOKEN' \
  --form 'first_name="User_First_Name"' \
  --form 'last_name="User_Last_Name"' \
  --form 'avatar=@"path/to/user_avatar.png"' \
  --form 'email="user_email@example.com"' \
  --form 'status="active"' \
  'https://example.com/api/agent/v1/agents'

استخدمنا في هذا الطلب الخيار form-- بدل data-- لتمرير البيانات ، لأن البيانات هنا متنوعة فهي تتضمن ملف صورة إضافة للبيانات المعتادة، ومن الضروري وضع الصورة المطلوبة للوكيل في مجلد العمل الحالي، أو أي مجلد يمكن الوصول إليه دون عوائق تتعلق بالصلاحيات.

سنشرح في هذا المقال طريقة الحصول على الملفات الشخصية للوكلاء ضمن مركز المساعدة.

طلب عرض بيانات الوكيل الحالي

يمكن الحصول على بيانات الملف الشخصي profile للوكيل الحالي المسجل في مركز المساعدة بإرسال طلب GET لنقطة الوصول Retrieve profile حيث يمكن لهذا الطلب عرض البيانات العامة للوكيل أو البيانات التفصيلية حسب قيمة المعامل الاختياري expand الممرر كمصفوفة في عنوان الطلب.

عرض بيانات الوكيل الحالي

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

curl --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/account/profile'

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

أما لو أردنا الحصول على معلومات تفصيلية أكثر عن الوكيل كفرق العمل التي ينتمي إليها، ونماذج التواصل التي يمتلك صلاحيات عليها، فسنمرر ذلك ضمن المعامل expand كما يلي:

curl --globoff \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/account/profile?expand[]=teams&expand[]=forms'

ننتبه جيدًا لكتابة قيم المعامل expand فأي خطأ املائي فيها يعني أن الواجهة البرمجية لن تفهم الطلب وستعيد الخطأ 400 Bad Request.

طلب عرض بيانات كافة الوكلاء

نرسل طلب من نوع GET لنقطة الوصول List all agents لعرض الملفات الشخصية لكافة الوكلاء المسجلين ضمن مركز المساعدة، كما يمكننا إرسال طلب GET لنقطة الوصول Retrieve an agent لعرض بيانات وكيل محدد مع تمرير الرقم التعريفي لهذا الوكيل كمعامل مسار ضمن عنوان الطلب.

عرض بيانات الوكلاء

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

curl --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/agents'

وللحصول على بيانات الوكيل رقم 1008 فقط، نكتب الطلب على النحو التالي:

curl --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/agents/1008'

طلب تعديل بيانات وكيل

يمكننا تعديل إعدادات حساب وكيل من خلال عدة نقاط وصول، إما من خلال إرسال طلب POST لنقطة الوصول Update profile لتعديل البيانات الشخصية للوكيل الحالي المسجل في مركز المساعدة كالاسم، وكلمة المرور، والصورة الشخصية، والبريد الإلكتروني، وحالة الظهور وغيرها.
كما يمكننا إرسال طلب PUT لنقطة الوصول Update an agent لتعديل إعدادات حساب وكيل محدد في مركز المساعدة بالاعتماد على رقمه التعريفي، وتجدر الإشارة إلى أن بإمكاننا هنا تعديل كلمة مرور الوكيل دون معرفة كلمة مروره الحالية بعكس نقطة الوصول Update profile التي تتطلب تمرير كلمة المرور الحالية عند التعديل. كما يمكننا إرسال طلب PUT لنقطة الوصول Update an agent permissions لتعديل صلاحيات وكيل معين بناءً على معرف الوكيل لا سيما الوكيل الذي لا ينتمي لأي فريق عمل.

تعديل بيانات الوكيل الحالي

لتعديل الاسم الأول، ومدة استلام رسالة الإشعارات للوكيل الحالي المسجل، وتعديل مدة استلامه للإشعارات لتصبح 12 ساعة بدلًا من 6 ساعات، نكتب الطلب التالي:

curl --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     -X POST \
     --data '{
         "first_name": "Saleh",
         "last_name": "Amin",
         "email": "agent@exampel.com",
         "notify_after": "12"
     }' \
     'https://example.com/api/agent/v1/account/profile'

تعديل بيانات وكيل محدد

لتعديل بعض خصائص الوكيل الذي يملك الرقم 1008 كتعديل كلمة المرور الخاصة به، وصناديق البريد التي يمكنه العمل عليها لتكون الصناديق رقم 110 و 1010، ومنحه صلاحية الوصول لمجموعة حقول مخصصة رقمها التعريفي 1016، سنكتب الطلب التالي:

curl -X PUT \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "first_name": "Saleh",
         "last_name": "Amin",
         "email": "agent@exampel.com",
         "status": "active",
         "password": "new_password",
         "password_confirmation": "new_password",
         "inbox_ids": [110, 1010],
         "field_group_ids": [1016]
     }' \
'https://example.com/api/agent/v1/agents/1008'

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

منح صلاحية الوصول لوكيل

لمنح صلاحية إدارة جهات الوصول للوكيل رقم 1008 ضمن مركز مساعدة له النطاق example.com والذي لا ينتمي لأي فريق عمل نكتب الطلب التالي:

curl -X PUT \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "permission": "contacts.admin",
         "value": "true"
     }' \
'https://example.com/api/agent/v1/agents/1008/permissions'

طلب حذف وكيل

قد نحتاج لإزالة وكيل لم يعد نشطًا أو لم يعد يحتاج للوصول لمركز المساعدة، ويمكننا القيام بذلك من خلال إرسال طلب DELETE إلى نقطة الوصول Delete an agent مع تمرير الرقم التعريفي للوكيل كمعامل مسار ضمن عنوان الطلب.

حذف وكيل محدد

يحذف المثال التالي الوكيل رقم 1008 من مركز مساعدة يملك النطاق example.com.

curl -X DELETE \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/agents/1008'