قراءة متطلبات حملة لعلامة تجارية

حافظ على ارتباط العلامة التجارية بحالة الاستخدام

استخدم معرّف العلامة التجارية الموجود في حسابك وقيمة حالة استخدام أعادتها قائمة التأهيل الخاصة بالعلامة التجارية نفسها. يتحقق سير عمل العميل من الملكية قبل طلب المزوّد. تأكد من أن حقل usecase في الكائن المُعاد يطابق القيمة المحددة. البحث الخاص بعلامة تجارية أو حالة استخدام واحدة لا يُثبت المتطلبات لعلامة أو حالة أخرى.

اقرأ المتطلبات الحالية

طبّق متطلبات المشغّلين المحددين معاً

يمكن أن تختلف متطلبات المشغّلين. عندما لا تُقدَّم قائمة مشغّلين صريحة، تأخذ البوابة في الاعتبار جميع البيانات الوصفية للمشغّلين في الاستجابة؛ أما القائمة غير الفارغة فتقصر الفحوصات على المعرّفات المحددة فيها. لا تستخدم عدد العينات أو الإقرارات الخاصة بالمشغّل الأول فقط. اختر المشغّلين من الاستجابة، وتحقق من الدعم والتأهيل، واستوفِ أعلى حد أدنى للعينات ينطبق، واستوفِ إقرارات الاشتراك وإلغاء الاشتراك والمساعدة المطلوبة عبر ذلك الاختيار بأكمله. ترفض البوابة معرّفات المشغّلين المحددة غير الموجودة في الاستجابة الحالية، وترفض أي اختيار لا يتضمن مشغّلاً مؤهلاً.

تصف المتطلبات ما يجب تقديمه؛ وهي لا تثبت أن عملية الموافقة لدى العميل أو محتوى الحملة يستوفيان تلك المتطلبات. اجمع عينات وإقرارات صادقة وممثِّلة للواقع. لا تفعّل الإقرارات تلقائياً لتمرير النموذج.

أعدّ العينات وردود المشتركين

يستخدم نموذج الحملة الحالي الحقول من sample1 إلى sample5 لعينات الرسائل. إذا تعذّر استيفاء المتطلبات ضمن النموذج المتاح، فتوقف وحلّ مسألة الاختيار مع فريق الدعم. بالنسبة لأي إقرار مشترك مفعّل، قدّم الكلمات المفتاحية ونص الرد المقابلين له: optinKeywords/optinMessage، optoutKeywords/optoutMessage، و helpKeywords/helpMessage. حافظ على اتساق العينات مع حالة الاستخدام المختارة ومع رسائل العميل الفعلية.

راجع قبل أي طلب تسجيل

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

التعامل مع فشل البحث عن المتطلبات

إذا فشل الطلب، أو أعاد JSON غير متوقع، أو لم يطابق حالة الاستخدام المحددة، فأبقِ النموذج غير مكتمل واسمح للعميل بإعادة المحاولة بعد حل الخطأ. لا تستبدل المتطلبات غير المتاحة بكائن فارغ، ولا تفترض أن غياب البيانات يعني عدم وجود متطلبات. احترم Retry-After واستخدم التراجع التدريجي عند حدود المعدل وإخفاقات التوفر.

الطلب

استخدم حساب API مفعّلاً عبر HTTPS من عنوان IP مصدر مسموح به. يدعم المسار الحالي سياسة مصادقة الحساب، بما في ذلك مصادقة Basic وحسابات API المفعّلة ذات الرمز الحامل (bearer). لا تستخدم بيانات اعتماد المزوّد.

أرسل GET مع معرّف العلامة التجارية وقيمة حالة الاستخدام المحددة في مسار عنوان URL. لا يلزم وجود نص للطلب.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/campaignBuilder/brand/$BRAND_ID/usecase/$USECASE"

الاستجابة

يعيد مسار TCR الحالي نص JSON الخاص بالسجل مباشرةً ويحافظ على حالة HTTP الخاصة به. ولا يضيف غلاف status/response القديم من الإصدار v3. المثال المختصر الخيالي ليس نتيجة تأهيل حية. تحقق من حالة HTTP وشكل JSON المتوقع قبل استخدامه. تتوقع البوابة كائناً تطابق قيمة usecase فيه حالة الاستخدام المحددة. توجد متطلبات المشغّلين ضمن mnoMetadata، مفهرسة حسب معرّف المشغّل. معرّف المشغّل والمتطلبات في المثال خيالية. قد تُعاد حقول أخرى من المزوّد.

شكل استجابة توضيحي؛ وليس بيانات حساب حية أو عرض سعر حالياً.

{
  "usecase": "2FA",
  "minSubUsecases": 0,
  "maxSubUsecases": 0,
  "mnoMetadata": {
    "12345": {
      "mnoSupport": true,
      "qualify": true,
      "minMsgSamples": 1,
      "reqSubscriberOptin": true,
      "reqSubscriberOptout": true,
      "reqSubscriberHelp": true,
      "noEmbeddedLink": false,
      "noEmbeddedPhone": false
    }
  }
}

الأخطاء

• 401: فشلت مصادقة الحساب. تحقق من بيانات اعتماد API وحالة التفعيل وقيود عنوان IP المصدر المطبّقة.
• 404: العلامة التجارية غير مرتبطة بالحساب الذي تمت المصادقة عليه، أو لا يستطيع المزوّد العثور على العلامة التجارية أو الاختيار المطلوب. يُعاد رفض الملكية المحلي قبل إرسال طلب إلى المزوّد.
• أخطاء السجل الأخرى: يتم الحفاظ على حالة HTTP ونص الاستجابة الواردين من المصدر الأعلى. حالة الاستخدام غير الصالحة أو غير المتاحة ليست مجموعة متطلبات فارغة ناجحة.
• 429: تم بلوغ حد طلبات الحساب أو حد طلبات المزوّد المشترك. احترم Retry-After.
• 502/503: إخفاق في توفر النقل أو المزوّد أو محدد المعدل. احتفظ بالنموذج وأعد المحاولة مع التراجع التدريجي.

التوفر والآثار الجانبية

• يتحقق طلب GET الذي تمت مراجعته من ملكية علامة تجارية قائمة، ويتصل بالسجل، ويكتب سجلات تدقيق الطلبات. وهو لا ينشئ علامة تجارية أو حملة، ولا يفرض رسوم تسجيل.
• البيانات الوصفية لرسوم المزوّد ليست عرض سعر تجزئة لعميل MultiTEL. تراجع البوابة تسعير الحساب بشكل منفصل قبل أي طلب تسجيل لاحق.
• يمكن أن يتغير التأهيل والمتطلبات. حدّثها للعلامة التجارية وحالة الاستخدام المحددتين قبل الإرسال. البحث الناجح ليس موافقة على حملة، ولا تعييناً لرقم، ولا إذناً ببدء إرسال الرسائل.