طلب أرقام هواتف من بادئة

الطلب من بادئة

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

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

إرسال طلب الشراء

استخدم حساب API مفعّلاً عبر HTTPS ومن عنوان IP مصدر مسموح به. اضبط المتغيرات وفق اختيارك الحالي من الدليل وإعدادات التوصيل المعتمدة لديك. يشتري الأمر التالي رقماً واحداً.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

يظهر أعلاه إرسال بيانات نموذج باستخدام POST. ويقرأ منسّق العملية أيضاً كائن JSON عندما تكون قيمة Content-Type هي application/json. تتجاوز حقول JSON حقول النموذج أو الطلب المطابقة لها. التزم بترميز واحد؛ ولا ترسل قيماً متعارضة في سلسلة الاستعلام ومتن الطلب.

معاملات اختيار الطلب والإشعارات
المعامل	المعنى
معرّف البادئة في المسار	معرّف UUID الخاص بالبادئة الذي يعيده الدليل. لا يمكن استبداله بمعرّف بلد أو منطقة أو سعر أو رقم منفرد.
quantity	أرسل عدداً صحيحاً من 1 إلى 100. القيمة الافتراضية هي 1. تُحوَّل القيم الأقل من 1 قسراً إلى 1؛ فهذا ليس طلباً للتحقق فقط. تؤدي القيم الأكبر من 100 إلى طرح استثناء قبل المعالجة المعتادة للاستجابة لدى منسّق العملية، لذا لا تعتمد على بنية JSON المعتادة له عند إرسال هذه القيمة غير الصالحة.
price_id	معرّف السعر العام للخطة المختارة. الاسم priceid هو اسم بديل قديم. قد يؤدي معرّف غير مطابق إلى اختيار خطة مختلفة احتياطياً دون تنبيه؛ ولا يشكّل هذا الحقل قفلاً صارماً للسعر. تحقّق من الحدود القصوى للأسعار في الحساب قبل الشراء، وافحص السعر المُعاد بعده.
channels	عدد القنوات في الخطة المختارة. عندما لا تُستخدم مطابقة تامة للسعر، يمكن أن يؤثر تطابق عدد القنوات في اختيار الخطة الاحتياطية. ولا يضمن هذا العدد بمفرده شراء خطة بعينها.
reference	التسمية التي تختارها لعملية الشراء أو الدفعة. استخدم قيمة ASCII قصيرة لا تتجاوز 255 بايت؛ إذ تُقتطع القيم الأطول. تُحفظ هذه القيمة مع عمليات الشراء الناجحة وتُضمَّن في إشعارات الاستدعاء الراجع عند تقديمها. قد تشترك طلبات منفصلة في المرجع نفسه. وهو ليس مفتاحاً لمنع تكرار التنفيذ: فقد يؤدي إرسال هذه العملية مجدداً إلى شراء أرقام إضافية واحتساب رسومها، حتى مع استخدام المرجع نفسه وحقول متطابقة.
webhook_url	عنوان URL اختياري للاستدعاء الراجع. استخدم نقطة نهاية HTTPS تتحكم فيها. تجتاز عناوين URL التي تستخدم HTTP وHTTPS أداة التحقق الأساسية الحالية؛ ويُتجاهل عنوان URL غير الصالح بدلاً من رفض الشراء. الاستدعاء الراجع إشعار إضافي، وليس دليلاً على إمكانية تكرار الطلب بأمان.

إعدادات التوصيل والتجديد

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

حقول الطلب الإضافية
الحقل	الاستخدام والتوافق
uri, uri2, uri3	الوجهة الأساسية والوجهات الإضافية للمكالمات الصوتية. قدّم وجهات مناسبة لوضعي التحويل والرنين المختارين.
forward_destination	وضع تحويل المكالمات الصوتية. الاسمان forwarding_destination وtype بديلان قديمان. عند إغفال الحقل، تُستخدم القيمة الافتراضية لمسار إتمام الشراء؛ ولا يُعد ترك الحقل فارغاً طريقة موثوقة لمسح تفضيل موجود.
ring_type	وضع رنين المكالمات الصوتية؛ والاسم ringtype بديل له. استخدم قيمة مدعومة من إعدادات الأرقام في حسابك.
sms_forward_destination, sms_uri	وضع توصيل الرسائل النصية القصيرة ووجهتها. الاسمان البديلان القديمان هما smsringtype وsmsuri. تطبّق بعض مسارات إتمام الشراء الوجهة الافتراضية للرسائل النصية القصيرة في الحساب عند ترك هذا الإعداد فارغاً. يعتمد توفر الرسائل النصية القصيرة على الرقم المختار وتفعيله أو تسجيله.
overflow	إعداد تجاوز السعة المطلوب. يؤثر توفر الخطة ومسار إتمام الشراء في ما إذا كان هذا الإعداد مدعوماً.
force_codec, force_dtmf	إعدادات الترميز وDTMF المطلوبة. الاسمان البديلان القديمان هما forcecodec وforcedtmf. تحقّق من الإعدادات المحفوظة للمخزون المختار.
origination_trunk_id	معرّف إعدادات وصلة ربط موجودة، حيثما ينطبق ذلك. لا يؤدي هذا إلى إنشاء وصلة ربط. عند إغفال الحقل، تُستخدم القيمة الافتراضية لإتمام الشراء.
autorenew	إعداد التجديد المطلوب. لا تفترض أن 0 يعطّل التجديد: فبعض مسارات إتمام الشراء تتعامل مع القيمة التي تُعدّ فارغة، بما فيها 0، على أنها الإعداد الافتراضي المفعّل. تحقّق من التجديد للرقم المشترى في البوابة، وغيّره عند الحاجة.

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

قراءة النتيجة كاملة

حلّل متن JSON وافحص status.code وstatus.msg حتى عندما ينجح طلب HTTP. ينشئ هذا المسار استجابة JSON الخاصة به، كما أن أداة المساعدة المشتركة للاستجابات لا تربط بالضرورة رمز التطبيق بحالة HTTP. قد تكون رموز التطبيق أعداد JSON أو سلاسل نصية رقمية. لا تشترط وجود status.results؛ فهو غير موجود في نتيجة الطلب المعتادة.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

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

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

عمليات الشراء الجزئية والنتائج غير المؤكدة

قد يصاحب رمز التطبيق 200 تحذير وعدد من الأرقام أقل مما طُلب. ولا يلغي فشل لاحق شراء الأرقام التي اشتُريت بالفعل. احتفظ بمعرّف الطلب والأرقام والرسالة المُعادة. طابق تلك الأرقام مع مخزونك ومعاملات حسابك قبل أن تقرر ما إذا كنت ستطلب الكمية المتبقية.

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

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

التسجيل والتفعيل

قد يظل الرقم المشترى أو المخصّص بحاجة إلى تسجيل أو تفعيل. إذا كانت قيمة needs_registration هي 1، فافحص restrictions وregistration_requirements. وقد يشير الأخير إلى v3/get_requirements مع قيمتي country وnumber_type. أكمل إجراءات الهوية أو العنوان المنطبقة، وتأكّد من حالة الرقم قبل الاعتماد عليه لاستقبال المكالمات أو الرسائل.

يصف features الإمكانات المعلنة؛ ولا يؤكد عمل التوجيه الفعلي أو الموافقة على الحملات أو توصيل الرسائل النصية القصيرة أو استقبال الفاكس. افحص إعدادات التوصيل المحفوظة، وأجرِ اختبار الخدمة المناسب عندما يكون الرقم مفعّلاً.

إشعارات الاستدعاء الراجع للطلبات

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

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

حالات الفشل التي يجب التعامل معها

نتائج التطبيق
النتيجة	الإجراء المطلوب
400 ونص يفيد بأن البادئة غير صالحة	راجع دليل البادئات مجدداً واستخدم المعرّف الحالي الوارد فيه. ميّز هذه الحالة عن نص يفيد بأن طلباً أصلياً لا يزال قيد التأكيد.
403 أو فشل متعلق بسياسة الحساب أو رصيده	راجع إذن الشراء والحدود القصوى للأسعار في الحساب وحدود الكمية والتمويل. قد تُمرَّر رموز تطبيق أخرى من عمليات التحقق هذه؛ فاحتفظ بالرسالة الفعلية.
404 أو عدم توفر مخزون	حدّث معلومات التوفر. لا تكرر محاولات الشراء من بادئة نفد مخزونها.
409 ونص يتعلق بتأكيد الشراء أو رفض المزوّد أو إلغاء الطلب	احتفظ بمعرّف الطلب المُعاد والرسالة الفعلية. طابق الطلب مع المخزون ومعاملات الحساب وبمساعدة الدعم قبل إرسال طلب شراء آخر. لا تجعل إعادة استخدام المرجع نفسه إرسال طلب آخر آمناً.
200 مع تحذيرات أو عدد أقل من الأرقام	اشتُريت بعض الأرقام. طابق التخصيص المُعاد والمعاملات مع السجلات قبل طلب المزيد.
فشل في الخادم أو النقل، أو استجابة غير قابلة للقراءة	تعامل مع النتيجة على أنها قد تكون غير مؤكدة إلى أن يتضح ما حدث من خلال المخزون والمعاملات.