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

محتويات الصفحة

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

    عرض الاستلامات الواردة إلى مركز المساعدة عبر النماذج

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

    لكن دعنا في البداية نستعرض مواصفات نقطة الاتصال form-submissions/ ومعاملات الاستعلام التي تقبلها.

    • عنوان URL لنقطة الاتصال:
      https://{your_subdomain}/api/agent/v1/form-submissions.
    • نوع الطلب: GET.
    • معاملات الاستعلام Query Parameters: وهي على النحو التالي:
      • after: نوعه مصفوفة array، يساعدك على عرض الاستلامات (البيانات) الواردة عبر النماذج بعد وقت وتاريخ معينين أو الاستلامات التي يتجاوز رقمها التعريفي id حد معين أو التي تحقق الشرطين معًا كما في المثال التالي: ["after[id] = 1","after[created_at] = datetimezone"]
      • before: نوعه مصفوفة array، يساعدك على عرض الاستلامات الواردة عبر النماذج قبل وقت وتاريخ معينين أو الاستلامات التي يقل رقمها التعريفي id عن حد معين أو التي تحقق الشرطين معًا كما في المثال التالي:
        ["before[id] = 1","before[created_at] = datetimezone"]
      • assign_to: نوعه مصفوفة array، يساعدك على عرض الاستلامات المُسندة إلى مستخدمين معينين في مركز المساعدة، وذلك بناءً على الرقم التعريفي للمستخدم id. علمًا أنك تستطيع معرفة الأرقام التعريفية للمستخدمين بإرسال طلب من نوع GET إلى نقطة الاتصال agents/.
      • contact_ids: نوعه مصفوفة array، يساعدك على عرض الاستلامات التي أرسلها عملاء أو جهات اتصال معينون إلى مركز المساعدة.
      • created_by: نوعه سلسلة نصية string، يأخذ إحدى القيمتين التاليتين حصرًا:
      • contact: يعرض جميع الاستلامات التي أنشأها أحد الأشخاص (جهات الاتصال).
      • agent: يعرض جميع الاستلامات التي أنشأها أحد مستخدمي -أو موظفي- مركز المساعدة.
      • form_ids: نوعه مصفوفة array، تكتب ضمنه الأرقام التعريفية للنماذج، ويساعدك على عرض الاستلامات الواردة عبر نموذج/ نماذج معينة.
      • form_submission_status_ids: نوعه مصفوفة array، تكتب ضمنه الأرقام التعريفية لحالات استلامات النماذج (مثل مفتوحة أو مؤرشفة أو غير ذلك)، ويساعدك على تصفية الاستلامات المعروضة تبعًا لحالة معينة أو مجموعة حالات معينة. علمًا أنك تستطيع معرفة الأرقام التعريفية لحالات الاستلامات المُعَرَّفة في مركز المساعدة بإرسال طلب من نوع GET إلى نقطة الاتصال form-submission-statuses/.
      • limit: نوعه عدد صحيح integer، يساعدك على التحكم بعدد الاستلامات المعروضة في الاستجابة، قيمته الافتراضية 6 ويمكنك إعطائه أي قيمة من 1 إلى 100.
      • locale: نوعه مصفوفة array، يساعدك على عرض الاستلامات الواردة إلى مركز المساعدة بلغة معينة، ويقبل القيمتين التاليتين حصرًا:
        • ar للغة العربية.
        • en للغة الإنجليزية.
      • sort: نوعه سلسلة نصية string، يساعدك على ترتيب المحادثات تصاعديًا أو تنازليًا تبعًا لعدة عوامل:
        • تاريخ ورود الاستلامات إلى مركز المساعدة: من أقدم استلام إلى أحدث استلام أو العكس باستخدام created_at.desc أو created_at.asc.
        • الرقم التعريفي للاستلامات: من أصغر رقم إلى أكبر رقم أو العكس باستخدام id.asc أو id.desc.

    أمثلة

    لنطبق الآن بعض الأمثلة باستخدام الأداة cURL على مركز مساعدة تجريبي يدعى "المناسب al-munasib" وله النطاق الفرعي al-munasib.zaetoon.com:

    مثال 1: عرض جميع الاستلامات الواردة إلى مركز المساعدة من دون أي شروط


    curl --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/form-submissions?limit=100'

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

    curl --globoff --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.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'

    مثال 3: عرض الاستلامات المُنشأة بواسطة جهات الاتصال فقط

    curl --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/form-submissions?created_by=contact'

    مثال 4: عرض الاستلامات التي تتصف بحالة معينة ولتكن الحالة "مفتوحة" مثلًا ذات الرقم التعريفي "2102" في مركز مساعدة "المناسب": 

    curl --globoff --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/form-submissions?form_submission_status_ids[]=2102'

    مثال 5: عرض الاستلامات المُسندة إلى مستخدم معين في مركز المساعدة، وليكن ذور الرقم "1434" مثلًا:

    curl --globoff --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/form-submissions?assign_to[]=1434'

    مثال 6: عرض الاستلامات الواردة على نموذج معين فقط له الرقم التعريفي "1048":

    curl --globoff --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/form-submissions?form_ids[]=1048'

    مثال 7: عرض الاستلامات التي أرسلتها جهات اتصال معينة إلى مركز المساعدة، وذلك اعتمادًا على الرقم التعريفي لجهة الاتصال:

    curl --globoff --header 'Authorization: Bearer your_token' 'https://al-munasib.zaetoon.com/api/agent/v1/form-submissions?contact_ids[]=431110&contact_ids[]=432651'
    محتويات الصفحة