تحميل قوائم خيارات تسجيل المراسلة

تحميل الخيارات قبل إنشاء نموذج التسجيل

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

اختيار قائمة خيارات

معالجة استجابة TCR مباشرة

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

الفصل بين خيارات القوائم والأهلية والتسعير

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

التعامل مع قوائم الخيارات غير المتاحة

احتفظ بالبيانات التي أدخلها العميل في النموذج إذا فشل الاستعلام. اعرض الخطأ، والتزم بـ Retry-After عند إرجاعه، وزد فترات الانتظار بين المحاولات تدريجيا. لا تكرر تحميل جميع القوائم ولا تتعامل مع خطأ في حد معدل الطلبات أو في النقل على أنه قائمة خيارات فارغة وصالحة. لا يتطلب طلب GET هذا مفتاحا لضمان عدم تكرار الأثر، ولا يُعاد تشغيله من مخزن ضمان عدم تكرار الأثر الخاص بعمليات التعديل.

الطلب

استخدم حساب API مفعّلا عبر HTTPS من عنوان بروتوكول إنترنت مصدري مسموح به. يدعم المسار الحالي سياسة مصادقة الحساب، بما فيها مصادقة Basic وحسابات API المفعّلة التي تستخدم رموز حامل. لا تستخدم بيانات اعتماد المزوّد.

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

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/enum/usecase?validSubUsecase=true"

الاستجابة

يعيد مسار TCR هذا متن السجل مباشرة مع حالة HTTP الخاصة به. ولا يستخدم الغلاف القديم status.code/status.msg/response في v3. تختلف بنى قوائم الخيارات: فبعضها يربط القيم بكائنات وصفية، وبعضها الآخر يربط القيم بسلاسل نصية. احتفظ بالمفاتيح القابلة للقراءة آليا عند إرسال نموذج لاحق. يوضح المثال الافتراضي المختصر لـ usecase خريطة ترابط قيمها كائنات، وليس قائمة فعلية أو مخططا مضمون الاكتمال. تحقّق من حالة HTTP ومن بنية JSON المتوقعة معا.

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

{
  "2FA": {
    "displayName": "Authentication",
    "description": "Example authentication use case"
  }
}

الأخطاء

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

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

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