التعامل مع استلامات النماذج

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

export TOKEN="YOUR_API_KEY"

عرض استلامات النماذج

لعرض جميع الاستلامات الواردة إلى مركز المساعدة عبر النماذج نرسل طلب GET إلى نقطة الوصول List all form submissions ويمكن تخصيص العديد من خيارات الفرز والتصفية لها.

ولعرض استلام معين نرسل طلب GET لنقطة الوصول Retrieve a form submission مع تمرير الرقم التعريفي للاستلام ضمن عنوان الطلب.

كافة الاستلامات

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

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

استلام واحد

لعرض الاستلام رقم 200 في مركز المساعدة نكتب الطلب التالي:

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

الاستلامات آخر شهر

لعرض الاستلامات الواردة لمركز خلال شهر معين مع ترتيبها من الأقدم إلى الأحدث نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/form-submissions?before[created_at]=2024-09-30T23%3A59%3A59&after[created_at]=2024-09-01T00%3A00%3A00&sort=created_at.asc" \
  -H "Authorization: Bearer @TOKEN" \
  --globoff

استلامات بحالة محددة

لعرض الاستلامات التي تملك الحالة مفتوحة، وبافتراض أن الرقم التعريفي لهذه الحالة 400 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/form-submissions?form_submission_status_ids[]=400" \
  -H "Authorization: Bearer @TOKEN" \
  --globoff

استلامات مُسندة لوكيل

لعرض كافة الاستلامات المسندة للوكيل رقم 1008، نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/form-submissions?assign_to[]=1008" \
  -H "Authorization: Bearer @TOKEN" \
  --globoff

حالات بشهر محدد

لعرض حالات استلامات بيانات النماذج ضمن مركز المساعدة والمُنشأة خلال الفترة من 2025/03/01 لغاية 2025/03/31 والتي تخص نموذج رقم 1012، وترتيب النتائج المعروضة تنازليًّا حسب تاريخ إنشاء الحالة من الأقدم إلى الأحدث نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/form-submission-statuses?before[created_at]=2025-03-31T23%3A59%3A59&after[created_at]=2025-03-01T00%3A00%3A00&limit=20&form_ids[]=1012&sort=created_at.desc" \
  -H 'Authorization: Bearer @TOKEN' \ 
  --globoff  

إضافة حالة استلام

يوفر مركز المساعدة حالتين افتراضيتين لكل نموذج هما الحالة المفتوحة والحالة المؤرشفة، ويمكن إنشاء حالات أخرى من خلال إرسال طلب POST لنقطة الوصول Create a form submission status وتمرير اسم الحالة ولونها وترتيبها ورقم النموذج الذي نرغب بإضافتها إليه في جسم الطلب.

حالة واحدة

لإضافة حالة جديدة باسم "قيد المعالجة" للنموذج رقم 1012 نكتب الطلب على النحو التالي:

curl "https://example.com/api/agent/v1/form-submission-statuses" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "قيد المعالجة",
    "color": "#f44336",
    "sort": 3,
    "form_id": "1012"
  }'

إضافة وسم استلام

يمكن إضافة وسم إلى استلام معين في مركز المساعدة بإرسال طلب من نوع POST لنقطة الوصول Add a form submission tag مع تمرير الرقم التعريفي للاستلام كمعامل ضمن عنوان الطلب، وتمرير اسم الوسم المطلوب في جسم الطلب.

وسم واحد

لإضافة الوسم "عاجل" للاستلام رقم 200 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/form-submissions/200/tags" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "عاجل"
  }'

تعديل الاستلامات

يمكن تعديل الاستلام بإرسال طلب PUT لنقطة الوصول Update a form submission كإسناد الاستلام لوكيل معين في مركز المساعدة، أو تغيير حالة الاستلام، مع تمرير الرقم التعريفي للاستلام في عنوان الطلب، وتمرير رقم الوكيل، أو الحالة الجديدة المطلوبة في جسم الطلب.

وكيل استلام

لإسناد الاستلام رقم 200 إلى الوكيل رقم 1008 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/form-submissions/200" \
  -X PUT \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assign_to": "1008"
  }'

حالة استلام

لتعديل حالة الاستلام التي لها الرقم التعريفي 200 من الحالة مفتوحة إلى الحالة مؤرشفة، وبافتراض أن الرقم التعريفي للحالة مؤرشفة هو 400 نكتب الطلب كالتالي:

curl "https://example.com/api/agent/v1/form-submissions/200" \
  -X PUT \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "form_submission_status_id": "400"
  }'

تعديل حالات الاستلام

يمكن تعديل اسم حالة استلام نموذج معين، أو تعديل لونها المميز، أو ترتيبها عبر إرسال طلب من نوع PUT لنقطة الوصول Update a form submission status وتمرير البيانات الجديدة للحالة في جسم الطلب.

كما يمكن إجراء تعديل متعدد لمجموعة حالات في نفس الوقت بإرسال طلب POST لنقطة الوصول Bulk save مع تمرير رقم النموذج كمعامل في عنوان الطلب، وبيانات الحالات المطلوبة في جسم الطلب.

حالة واحدة

لتعديل اسم حالة الاستلام "قيد المعالجة" للنموذج رقم 1012 بحيث نغير اسم الحالة إلى "بانتظار رد الفريق التقني" بافتراض رقم هذه الحالة هو 500، إلى جانب تعديل لونها إلى الأسود وترتيبها إلى 1، نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/form-submission-statuses/500" \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer @TOKEN" \
  -d '{
    "name": "بانتظار رد الفريق التقني",
    "color": "#000000",
    "sort": 1
  }'

عدة حالات

لنفرض لدينا ثلاث حالات لنموذج رقم 1012 وهي "مفتوحة" و"مؤرشفة" و"بانتظار رد الفريق التقني"، وأردنا إرسال طلب تعديل لحالات النماذج يتضمن إضافة حالة جديدة باسم "تجريبية" مثلًا، وحذف حالة "بانتظار رد الفريق التقني" وتعديل ترتيب الحالات المتبقية لتصبح الحالة "تجريبية" بالترتيب الأول، والحالة "مفتوحة" بالترتيب الثاني، والحالة "مؤرشفة" بالترتيب الثالث، سنكتب الطلب على النحو التالي:

curl "https://example.com/api/agent/v1/forms/1012/statuses/bulk-save" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer @TOKEN" \
  -d '{
    "statuses": [
      {"name":"تجريبية","color":"#f44336","sort":0},
      {"id":300,"name":"مفتوحة","color":"#009688","sort":1},
      {"id":"400","name":"مؤرشفة","color":"#4caf50","sort":2}
    ]
  }'

حذف وسم من استلام

لحذف وسم من استلام معين نرسل طلب DELETE لنقطة الوصول Delete a form submission tag مع تمرير كل من الرقم التعريفي للاستلام، والرقم التعريفي للوسم كمعاملات ضمن عنوان الطلب.

وسم واحد

لحذف الوسم رقم 600 من الاستلام رقم 200 نكتب الطلب على النحو التالي:

curl "https://example.com/api/agent/v1/form-submissions/200/tags/500" \
  -X DELETE \
  -H "Authorization: Bearer @TOKEN"

حذف حالة استلام

لحذف حالة استلام محددة لنموذج في مركز المساعدة، نرسل طلب من نوع DELETE لنقطة الاتصالDelete a form submission status مع تمرير الرقم التعريفي لهذه الحالة ضمن عنوان الطلب.

حالة واحدة

يحذف المثال التالي الحالة رقم 300 من مركز المساعدة:

curl "https://example.com/api/agent/v1/form-submission-statuses/300" \
  -X DELETE \
  -H "Authorization: Bearer @TOKEN"