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

سنشرح في هذا المقال التعامل مع الوكلاء أو موظفي الدعم الفني ضمن مركز المساعدة باستخدام الواجهة البرمجية لزيتون. سنوضح طريقة عرض بيانات الوكلاء، وإنشاء وكلاء جدد، وتعديل بياناتهم، أو حذفهم. ولتطبيق الأمثلة، سنفترض وجود مركز مساعدة على النطاق example.com، ومفتاح الواجهة البرمجية لزيتون مخزّن ضمن المتغير TOKEN$ لاستخدامه في الطلبات المختلفة.

export TOKEN="YOUR_API_KEY" 

عرض الوكلاء

لعرض بيانات كافة الوكلاء المسجلين ضمن مركز المساعدة نرسل طلب من نوع GET لنقطة الوصول List all agents.

ولعرض بيانات وكيل محدد يمكننا إرسال طلب GET لنقطة الوصول Retrieve an agent مع تمرير الرقم التعريفي لهذا الوكيل في عنوان الطلب.

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

كافة الوكلاء

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

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

وكيل واحد

لعرض البيانات الشخصية للوكيل رقم 1008، نكتب الطلب على النحو التالي:

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

الوكيل الحالي

لعرض البيانات الأساسية للوكيل الحالي المسجل في مركز المساعدة، سنكتب الطلب التالي:

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

ولعرض معلومات تفصيلية أكثر عن هذا الوكيل نمرر المعامل expand في عنوان الطلب كما يلي:

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

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

إنشاء وكيل

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

وكيل واحد

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

curl "https://example.com/api/agent/v1/agents" \
   -X POST \
   -H "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"'

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

تعديل وكيل

لتعديل كافة بيانات وكيل محدد في مركز المساعدة بالاعتماد على رقمه التعريفي نرسل طلب PUT لنقطة الوصول Update an agent.

وكيل واحد

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

curl "https://example.com/api/agent/v1/agents/1008" \
   -X PUT \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer @TOKEN" \
   -d '{
         "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]
    }'

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

تعديل صلاحيات وكيل

ولتعديل صلاحيات الوكيل فقط نرسل طلب PUT لنقطة الوصول Update an agent permissions مع تمرير الرقم التعريفي للوكيل في عنوان الطلب.

وكيل واحد

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

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

حذف وكيل

لحذف وكيل من مركز المساعدة، نرسل طلب DELETE لنقطة الوصول Delete an agent مع تمرير الرقم التعريفي للوكيل في عنوان الطلب.

وكيل واحد

يحذف الطلب التالي الوكيل رقم 1008 من مركز المساعدة:

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