إدارة الحقول المخصصة

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

export TOKEN="YOUR_API_KEY"

عرض مجموعات الحقول

لعرض كافة مجموعات الحقول المخصصة المعرفة في مركز المساعدة نرسل طلب GET إلى نقطة الوصول List custom fields.

ولعرض مجموعة حقول مخصصة بعينها نرسل طلب GET إلى نقطة الوصول Show custom field مع تمرير الرقم التعريفي للمجموعة المطلوبة ضمن عنوان الطلب.

كافة المجموعات

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

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

مجموعة واحدة

لعرض مجموعة الحقول المخصصة التي لها الرقم التعريفي 1013 نكتب الطلب التالي:

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

حقول الوكلاء

لعرض الحقول المخصصة الخاصة بوكلاء مركز المساعدة نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/custom-fields?resource=agent" \
  -H "Authorization: Bearer @TOKEN"

الحقول النشطة

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

curl "https://example.com/api/agent/v1/custom-fields?statuses[]=active&expand[]=fields" \
  -H "Authorization: Bearer @TOKEN" \
  --globoff

إنشاء مجموعة حقول مخصصة

لإنشاء مجموعة حقول مخصصة في مركز المساعدة نرسل طلب POST إلى نقطة الوصول Create custom field مع تحديد المورد المطلوب إنشاء الحقول له وخصائص الحقول المختلفة في جسم الطلب.

حقول الوكلاء

لإنشاء مجموعة حقول مخصصة جديدة خاصة بالوكلاء تتضمن حقل العنوان ليكون حقل نصي غير مطلوب، وحقل العمر وهو قائمة خيارات لتحديد الفئة العمرية للوكيل وهو حقل مطلوب نكتب الطلب على النحو التالي:

curl "https://example.com/api/agent/v1/custom-fields" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "مجموعة الحقول الجديدة",
    "sort": 0,
    "resource": "agent",
    "fields": [
      {
        "label": "العنوان",
        "placeholder": "اكتب عنوانك التفصيلي هنا",
        "hint": "اذكر اسم الدولة والمدينة",
        "type": "text",
        "sort": 0,
        "grid": "100",
        "required": false,
        "status": "active"
      },
      {
        "label": "العمر",
        "placeholder": "اختر فئتك العمرية من القائمة",
        "hint": "قائمة بالفئات العمرية",
        "type": "select",
        "sort": 1,
        "grid": "50",
        "required": true,
        "status": "active",
        "options": [
          {"value": "18-25"},
          {"value": "26-45"},
          {"value": "> 45"}
        ]
      }
    ],
    "display": "tab",
    "team_ids": [1009],
    "agent_ids": [1008, 108]
  }'

تعديل الحقول المخصصة

لتعديل كافة إعدادات مجموعة الحقول المخصصة نرسل طلب PUT إلى نقطة الوصول Update custom field مع تمرير الرقم التعريفي لمجموعة الحقول المخصصة المطلوب تعديلها في عنوان الطلب، والبيانات المطلوب تعديلها في جسم الطلب.

مجموعة حقول

لتعديل مجموعة الحقول المخصصة التي تملك الرقم التعريفي 1013 بحيث نعدل ترتيبها ليصبح 1، ونعدل حقل العنوان فيها ليصبح حقل إجباري، ونغير تسمية حقل العمر، وحجمه، وقائمة خياراته سنكتب الطلب التالي:

curl "https://example.com/api/agent/v1/custom-fields/1013" \
  -X PUT \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "مجموعة الحقول الجديدة",
    "sort": 1,
    "status": "active",
    "fields": [
      {
        "label": "العنوان",
        "sort": 1,
        "required": true,
        "type": "text",
        "id": "35736"
      },
      {
        "label": "كم عمرك؟",
        "sort": 0,
        "grid": "25",
        "type": "select",
        "options": [
          { "value": "19-25" },
          { "value": "26-45" },
          { "value": "> 45" }
        ],
        "id": "35737"
      }
    ]
  }'

ترتيب الحقول المخصصة

لإعادة ترتيب مجموعات الحقول المخصصة العائدة لنفس المورد في مركز المساعدة نرسل طلب POST لنقطة الوصول Sort Custom fields مع تمرير الأرقام التعريفية للحقول المطلوبة وترتيبها الجديد في جسم الطلب.

مجموعة حقول

لإعادة ترتيب مجموعات الحقول المخصصة للأشخاص نكتب الطلب على النحو التالي:

curl "https://example.com/api/agent/v1/custom-fields/bulk-sort" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_fields": [
      { "id": 2424, "sort": 0 },
      { "id": 2421, "sort": 1 },
      { "id": 2423, "sort": 2 },
      { "id": 2422, "sort": 3 }
    ]
  }'

حذف حقول مخصصة

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

مجموعة حقول

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

curl "https://example.com/api/agent/v1/custom-fields/1013" \
  -X DELETE \
  -H "Authorization: Bearer @TOKEN"