عرض بادئات الأرقام لمنطقة

قبل البدء

اختر منطقة باستخدام getareas. انسخ معرّف المنطقة من الاستجابة أو من رابط next_function المعاد. لمنطقة في الولايات المتحدة أو كندا، استخدم getstates إذا أردت حصر النتائج في ولاية أو مقاطعة واحدة.

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

تحقق من status.code في جسم JSON، إضافةً إلى حالة HTTP. توجد النتائج الناجحة في المصفوفة response. تُرتّب الاستجابة افتراضيًا بحسب الاسم. available قيمة تقديرية، ولا تغني مؤشرات الدليل عن التحقق من الإمكانات الفعلية للرقم المختار ومتطلبات تسجيله.

اختيار الخطوة التالية

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

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

خيارات العرض المتقدمة

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

الطلب

استخدم بيانات اعتماد حساب واجهة برمجة التطبيقات المفعّل لديك عبر HTTPS. تُدعم مصادقة Basic ورموز bearer لحسابات واجهة برمجة التطبيقات المفعّلة؛ وتُطبّق قيود الحساب.

استخدم GET وأرسل المعاملات الاختيارية في سلسلة الاستعلام. لا تعتمد على الرجوع إلى جسم نموذج الويب.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/v3/getprefixes/$AREA_ID?state=NY"

الاستجابة

بنية تغليف JSON القياسية status/response. يحصي status.results الصفوف المعادة، بما فيها نتائج أخذ العينات أو التجميع. يحتوي response على كائنات البادئات. لا تُعاد حقول أسعار. في الاستجابة العادية غير المجمّعة، يكون uuid معرّف البادئة؛ ويكون area_uuid وcountry_uuid معرّفين معادين؛ ويحتوي prefix وname على معلومات للعرض؛ ويكون available تقديرًا للتوفر وليس حجزًا؛ ويصف needs_registration وrestrictions معلومات التسجيل؛ وتكون sms_coverage وis_mobile وnumber_type مؤشرات من الدليل، وليست ضمانًا لإمكانات رقم معين. قد يكون number_type فارغًا أو سلسلة أخرى من الدليل، لذلك لا تشترط مجموعة قيم ثابتة. يكون state سلسلة قد تكون فارغة أو تحتوي على تنسيق من الدليل. وقد يكون latitude وlongitude فارغين. ويكون metered وoverflow مؤشرين من الدليل، وليسا مبالغ مالية. يحدد returns_numbers مسار عرض قائمة الأرقام (1) أو مسار تخصيص رقم وقت الطلب (0). ويحدد next_function ذلك المسار التالي. تحتوي الاستجابات المجمّعة أيضًا على إمكانات مدمجة، بما فيها قيم بديلة للإمكانات؛ فلا تفسرها على أنها إمكانات متحقق منها لكل رقم.

بنية الاستجابة للتوضيح فقط؛ لا تتضمن بيانات حساب مباشرة ولا عرض سعر حالي.

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "uuid": "PREFIX_ID_FROM_RESPONSE",
      "area_uuid": "AREA_ID_FROM_RESPONSE",
      "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
      "prefix": "+1212",
      "name": "Example area",
      "metered": 0,
      "overflow": 0,
      "needs_registration": 0,
      "restrictions": "",
      "state": "NY",
      "country_iso": "US",
      "is_mobile": 0,
      "number_type": "local",
      "latitude": "",
      "longitude": "",
      "available": 12,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getnumbers/PREFIX_ID_FROM_RESPONSE"
    }
  ]
}

الأخطاء

• 404: Invalid area ID: احصل على معرّف منطقة حالي من استدعاءات الاكتشاف.
• 404: State filter is only available for US and CA: احذف state للبلدان الأخرى.
• 404: Invalid state: استخدم ولاية أو مقاطعة يعيدها getstates لهذا البلد.
• 404: No prefixes found: لم تُعَد أي صفوف مطابقة من الدليل. لا يثبت ذلك أن رقمًا معينًا لا يمكن طلبه مطلقًا.
• 500: خطأ: 'Failed loading prefixes': فشل البحث في الدليل. حاول لاحقًا، واتصل بالدعم إذا استمر الأمر.

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

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