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

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

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

export TOKEN="YOUR_API_KEY"

طلب إضافة استلامات للنماذج

يمكن للوكيل إضافة استلام form submission عن شخص أو جهة اتصال معينة بإرسال طلب من نوع POST إلى نقطة الوصول Create a form submission مع تمرير أسماء حقول النموذج -التي تولدها الواجهة البرمجية تلقائيًا بصيغة مشابهة للتالي 01j3mnqd7vjned3mefw5xfx33p- وتمرير الرقم التعريفي للنموذج، وبالإمكان عرض قائمة بالنماذج المُعَرَّفة ضمن مركز المساعدة بإرسال طلب GET إلى نقطة الوصول List all forms.

إضافة استلام لشخص

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

يجب أن يكون الوكيل مسجلًا في مركز المساعدة ويملك الصلاحيات اللازمة، إذ سيُمرر رمز الوصول access token الخاص بالوكيل والذي تعيده الواجهة بعد عملية تسجيل الدخول في ترويسة الطلب POST على النحو التالي:

curl -X POST \
  --header 'Authorization: Bearer @TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "form_id": 1048,
    "01j3mnqd7mcyyxzs9te09s57p9": "contact_name",
    "contact_id": "432651",
    "01j3mnqd7vjned3mefw5xfx33p": "contact_mail@example.com",
    "01j3mnqd88q4jsrmnp1zt3e14k": "company_name",
    "01j3mnqd8ep5fxqj03jvcnt15y": "https://contact_example.com",
    "01j3mnqd82zeqxwmmb1xp1mqxy": {
      "country_code": 999,
      "number": 123456489
    },
    "01j3mnqd8m53m7rearf6eztwp8": "type_your_message_details",
    "01j8waqve6df8pqjvnp2qcb310": {
      "files": ["type_base64_code_for_your_file"]
    }
  }' 'https://example.com/api/agent/v1/form-submissions'

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

وتجدر الإشارة لأنه في حال احتوى النموذج حقلًا من النوع contact_phone_number لكتابة رقم جوال الشخص، سنمرره ضمن الطلب POST بهيئة كائن مؤلف من عنصرين هما رمز الدولة، ورقم الهاتف. وفي حال تضمن النموذج حقلًا خاصًا بإرفاق الملفات files، فيمكننا تمريرها ضمن طلب إنشاء الاستلام بهيئة مصفوفة من السلاسل النصية تمثل ترميز Base64 المقابل لكل ملف كما يلي:

"01j8waqve6df8pqjvnp2qcb310" : {
"files": ["file1_base64_code", "file2_base64_code"]
}

أو من خلال رفعها مسبقًا إلى خادم زيتون باستخدام إحدى نقطتي الوصول Upload files أو Upload an image ثم تمرير الأرقام التعريفية للملفات المرفوعة ضمن طلب إنشاء الاستلام كما يلي:

"01j8waqve6df8pqjvnp2qcb310" : {
"ids": [file1_id, file2_id]
}

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

طلب عرض استلام

يمكنك الحصول على استلام معين في مركز المساعدة من خلال إرسال طلب من نوع GET لنقطة الوصول Retrieve a form submission مع تمرير الرقم التعريفي للاستلام كمعامل ضمن عنوان الطلب.

عرض استلام محدد

لعرض الاستلام رقم 200 في مركز مساعدة له النطاق example.com، وترتيب ملاحظاته من أحدث ملاحظة إلى أقدم ملاحظة نكتب الطلب التالي:

curl --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/form-submissions/200?notes_sort=desc'

طلب عرض كافة الاستلامات

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

عرض جميع الاستلامات

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

curl --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/form-submissions?limit=100'

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

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

curl --globoff \
     --header 'Authorization: Bearer @TOKEN' \
     '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'

عرض استلامات لها حالة محددة

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

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

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

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

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

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

نرسل طلب PUT لنقطة الوصول Update a form submission من أجل إسناد الاستلام لوكيل معين في مركز المساعدة، أو تغيير حالة الاستلام من مفتوحة إلى مؤرشفة مثلًا حسب الحالات المُعَرَّفة في مركزنا، مع تمرير الرقم التعريفي للاستلام في عنوان الطلب، وتمرير رقم الوكيل، أو الحالة الجديدة المطلوبة في جسم الطلب.

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

لإسناد الاستلام رقم 200 إلى الوكيل رقم 1008في مركز مساعدة له النطاق example.com نكتب الطلب التالي:

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

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

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

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

طلب إضافة وسم لاستلام نموذج

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

إضافة وسم جديد لاستلام

لإضافة الوسم "عاجل" إلى الاستلام رقم 200 في مركز مساعدة له النطاق example.com.

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

مع العلم أن بإمكاننا كتابة أي وسم في الطلب، حتى إذا كان وسمًا جديدًا غير موجود في مركز المساعدة من قبل.

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

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

حذف وسم محدد

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

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

طلب إنشاء حالة استلام جديدة

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

إنشاء حالة استلام

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

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

طلب عرض كافة حالات الاستلامات

يمكننا الحصول على قائمة بكافة حالات النموذج بداية من استلامه وحتى الانتهاء من معالجته من خلال إرسال طلب من نوع GET لنقطة الوصول List all form submission statuses.

عرض حالات الاستلام في شهر محدد

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

curl --globoff \
     --header 'Authorization: Bearer @TOKEN' \
     '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'

طلب عرض حالة استلام

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

عرض حالة استلام محددة

يعرض المثال التالي بيانات حالة الاستلام ذات الرقم 300 في مركز مساعدة له النطاق example.com:

curl --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/form-submission-statuses/300'

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

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

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

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

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

طلب تعديل حالة استلام

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

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

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

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

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

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

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

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

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

طلب عرض ملاحظات الاستلام

لعرض كافة الملاحظات المسجلة حول استلام نموذج معين في مركز المساعدة نرسل طلب GET لنقطة الوصول List all form submission notes مع تمرير الرقم التعريفي للاستلام المطلوب في عنوان الطلب.

عرض الملاحظات بعد تاريخ محدد

لعرض الملاحظات المكتوبة عن الاستلام رقم 200 في مركز مساعدة له النطاق example.com، وذلك بعد تاريخ 2025/04/01 مع ترتيبها من الأقدم إلى الأحدث نكتب الطلب التالي:

curl --globoff \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/form-submissions/200/notes?after[created_at]=2025-04-01T00%3A00%3A00&limit=10&sort[created_at]=asc'

طلب إنشاء ملاحظة لاستلام

لإنشاء ملاحظة عن استلام معين نرسل طلب من نوع POST إلى نقطة الوصول Create a form submission note مع تمرير الرقم التعريفي للاستلام في عنوان الطلب وبيانات الملاحظة في جسم الطلب.

إضافة ملاحظة جديدة

لإضافة ملاحظة جديدة تتضمن مرفق إلى الاستلام رقم 200 في مركز مساعدة له النطاق example.com، سنبدأ أولًا برفع مرفق الملاحظة إلى الخادم بإرسال الطلب التالي:

curl -X POST \
     --header 'Authorization: Bearer @TOKEN' \
     --form 'files[]=@"/Path/to/your/to/file.pdf"' \
     --form 'belongs_to="forms"' \
     'https://example.com/api/agent/v1/files'

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

curl -X POST \
     --header 'Authorization: Bearer @TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
       "details": "type_your_note",
       "files": [1013]
     }' \
     'https://example.com/api/agent/v1/form-submissions/200/notes'

طلب تعديل ملاحظة استلام

لتعديل ملاحظة استلام معين نرسل طلب PUT لنقطة الوصول Update a form submission note

مع تمرير رقم الملاحظة ورقم الاستلام في عنوان الطلب، وبيانات الملاحظة في جسم الطلب

تعديل ملاحظة محددة

لتعديل المحتوى النصي للملاحظة رقم 1014ضمن مركز مساعدة له النطاق الفرعي example.com والمكتوبة حول الاستلام رقم 200 مع إضافة ملف جديد لمرفقاتها وليكن رقمه 1013 سنكتب الطلب التالي:

curl -X PUT \
     --header 'Authorization: Bearer @TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
       "details": "type_your_new_text",
       "attachments": [1013]
     }' \
     'https://example.com/api/agent/v1/form-submissions/200/notes/1014' 

طلب حذف ملاحظة من استلام

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

حذف ملاحظة محددة

لحذف الملاحظة رقم 1014 من الاستلام رقم 200 في مركز مساعدة له النطاق example.com نكتب الطلب التالي:

curl -X DELETE \
  --header 'Authorization: Bearer @TOKEN' \
  'https://example.com/api/agent/v1/form-submissions/200/notes/1014'