الحصول على حالات تسليم بيانات النماذج

تميّز حالات النماذج form submission statuses المراحل المختلفة التي يمر بها طلب العميل المُرسل لمركز المساعدة عبر نماذج التواصل بدايةً من استلامه وحتى الانتهاء من معالجته، فيمكنك مثلًا تمييز الطلبات التي ما زالت مفتوحة عن تلك التي يجري العمل عليها أو المغلقة، وسنعرض في هذا المقال طريقة الحصول على حالات النماذج هذه من خلال الواجهة البرمجية لزيتون.

الحصول على قائمة بحالات تسليم النماذج

يمكنك إرسال طلب من نوع GET لنقطة الاتصال form-submission-statuses/ لعرض قائمة بالحالات التي يمكنك إعطاؤها للاستلامات الواردة إلى مركز المساعدة عبر النماذج، وذلك وفق التالي:

• عنوان URL لنقطة الاتصال:

https://{your_subdomain}/api/agent/v1/form-submissions-statuses.

• نوع الطلب: GET.
• معاملات الاستعلام Query Parameters: وفق التالي:
• • after نوعه مصفوفة array، يساعدك على عرض:
  • • الحالات المُنشأة بعد وقت وتاريخ معينين، مثال: ["after[created_at] = datetimezone"].
    • الحالات التي يتجاوز رقمها التعريفي id حد معين، نحو: ["after[id] = 1"].
    • الحالات التي تتجاوز قيمة sort فيها حد معين، مثلًا ["after[sort] = 1"] (علمًا أن sort هو مُعَامِل يشير إلى تسلسل (أو ترتيب) داخلي للحالة ضمن مجموعة حالات النموذج).
    • الحالات التي تحقق عدد من الشروط السابقة مثل:
      ["after[id] = 1","after[created_at] = datetimezone","after[sort] = 1"]
  • before: نوعه مصفوفة array، يساعدك على عرض:
  • • الحالات المُنشأة قبل وقت وتاريخ معينين، مثال: ["before[created_at] = datetimezone"].
    • الحالات التي يقل رقمها التعريفي id حد معين، نحو: ["before[id] = 1"].
    • الحالات التي تقل قيمة sort فيها حد معين، مثلًا ["before[sort] = 1"] (علمًا أن sort هو مُعَامِل يشير إلى تسلسل (أو ترتيب) داخلي للحالة ضمن مجموعة حالات النموذج).
    • الحالات التي تحقق عدد من الشروط السابقة معًا مثل: ["before[id] = 1","before[created_at] = datetimezone","before[sort] = 1"]
  • form_ids نوعه مصفوفة array، تكتب ضمنه الأرقام التعريفية للنماذج، ويساعدك على عرض الحالات الخاصة بنماذج معينة.
  • limit نوعه عدد صحيح integer، يساعدك على التحكم بعدد الحالات المعروضة في الاستجابة، قيمته الافتراضية 6 ويمكنك إعطائه أي قيمة من 1 إلى 100.
  • sort نوعه سلسلة نصية string، يساعدك على ترتيب المحادثات تصاعديًا أو تنازليًا تبعًا لعدة عوامل:
  • • الرقم التعريفي للحالة: من أصغر رقم إلى أكبر رقم أو العكس باستخدام id.asc أو id.desc.
    • قيمة sort للحالة: من أصغر قيمة إلى أكبر قيمة أو العكس باستخدام sort.asc أو sort.desc.
    • تاريخ إنشاء الحالة: من أقدم حالة إلى أحدث حالة أو العكس باستخدام created_at.desc أو created_at.asc.

مثال

لنطبق مثالًا عمليًّا على مركز مساعدة تجريبي على منصة زيتون يدعى "المناسب" وله النطاق الفرعي https://al-munasib.zaetoon.com.

لنعرض مثلًا حالات استلامات بيانات النماذج ضمن مركز مساعدة "المناسب" المُنشأة خلال الفترة من 2024/7/1 لغاية 2024/7/31 والتي تخص نموذج "تواصل معنا" ذو الرقم التعريفي "1048" ضمن المركز، وترتيب النتائج المعروضة تنازليًّا حسب تاريخ إنشاء الحالة من الأقدم إلى الأحدث:

curl --globoff --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/form-submission-statuses?before[created_at]=2024-07-31T23%3A59%3A59&after[created_at]=2024-07-01T00%3A00%3A00&limit=20&form_ids[]=1048&sort=created_at.desc'