عرض مناطق التغطية لبلد

بعد اختيار البلد (وللولايات المتحدة أو كندا، اختيار ولاية أو مقاطعة اختياريًا عبر getstates)، استدعِ getareas لمعرفة المناطق التي تُعرض فيها الأرقام. احتفظ بمعرّف المنطقة uuid للخطوة التالية.

تؤدي كل منطقة إلى إحدى الخطوتين التاليتين:

• available > 0: قيمة next_function هي v3/getprefixes/{uuid}، مع إلحاق ?state= عند تطبيق مرشح ولاية أو مقاطعة. استخدم هذا الرابط لتصفح بادئات الأرقام.
• available = 0: للمنطقة بادئات أرقام، لكن لا يوجد مخزون، وتكون قيمة next_function هي v3/order/{uuid}. راجع وثائق طلب الشراء لمعرفة متطلبات هذه الخطوة.

available هو إجمالي المنطقة بالكامل، حتى عند التصفية بحسب الولاية أو المقاطعة. يقبل مرشح الولاية أو المقاطعة رمزًا أو اسمًا كاملًا، لكنه يعمل فقط مع US وCA. إذا أعاد المرشح No areas found، فحاول مجددًا من دونه. تُنفّذ الفحوص بالترتيب التالي: رمز بلد مفقود، ثم بلد غير معروف، ثم مرشح ولاية أو مقاطعة لبلد آخر، ثم ولاية أو مقاطعة غير صالحة، ثم عدم وجود مناطق مطابقة. تُعيد كل حالة من هذه الحالات الرمز 500 أو 404 في status.code، من دون تعيين حالة HTTP مطابقة.

الطلب

مطلوب: مصادقة HTTP بنظام Basic أو رمز Bearer (راجع المصادقة واستجابات واجهة برمجة التطبيقات). عند فشل المصادقة، تُرسل استجابة HTTP 401 قبل تنفيذ الاستعلام.

GET مع isocode في المسار، والمعاملين الاختياريين state وpid في سلسلة الاستعلام. إذا حُذف مقطع المسار، يُقرأ بدلًا منه حقل isocode مرمّز بصيغة نماذج الويب.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

الاستجابة

بنية التغليف القياسية. عند النجاح، تكون قيمة status.code هي 200، وقيمة status.msg هي 'Results: N'، وقيمة status.results هي N، ويكون response قائمة مرتبة بحسب اسم المنطقة. الحقول: uuid (معرّف غير دال للمنطقة تستخدمه الخطوة التالية)؛ country_uuid (معرّف غير دال للبلد من 32 محرفًا، لا يلزم لاحقًا)؛ name؛ area_type وnumber_type (أوصاف في الدليل؛ ولا تمثل الإدخالات بالضرورة أنواع أرقام محلية)؛ country_iso؛ is_mobile (0 أو 1، بحسب مؤشرات الجوال للمنطقة؛ وتكون قيمته دائمًا 0 لـ US ما لم يكن حسابك مفعّلًا لاستخدام أرقام الجوال في US)؛ available (إجمالي المخزون عبر بادئات المنطقة المطابقة، من دون الاقتصار على الولاية أو المقاطعة المطلوبة)؛ sms_coverage (0 أو 1)؛ returns_numbers (0 أو 1، أعلى مؤشر بين بادئات المنطقة)؛ latitude وlongitude؛ state_iso؛ next_function. state_iso: عند تطبيق مرشح ولاية أو مقاطعة، تكون القيمة هي رمز المرشح بعد تحديده. بالنسبة إلى US وCA من دون مرشح، تُستخدم قيمة الولاية أو المقاطعة التي يطابق اسمها اسم المنطقة، وإلا فقيمة المنطقة المخزنة، وإلا فرمز مستمد من بيانات بادئات المنطقة. بالنسبة إلى البلدان الأخرى، تُستخدم القيمة المخزنة وقد تكون فارغة. تكون قيمة next_function هي 'v3/getprefixes/{uuid}' (مع إضافة '?state={code}' عند التصفية) عندما تكون available أكبر من 0، وإلا فتكون 'v3/order/{uuid}'. تُحذف المناطق التي ليس لها أي بادئة مطابقة. وتُعاد المناطق التي لها بادئات ولكن لا مخزون لديها بقيمة available تساوي 0.

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

{
  "status": {
    "code": 200,
    "msg": "Results: 2",
    "results": 2
  },
  "response": [
    {
      "uuid": "0000000000000000000000000000a001",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Example City",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 58,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "latitude": "40.0000",
      "longitude": "-75.0000",
      "state_iso": "NY",
      "next_function": "v3/getprefixes/0000000000000000000000000000a001"
    },
    {
      "uuid": "0000000000000000000000000000a002",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Sample Town",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 0,
      "sms_coverage": 0,
      "returns_numbers": 0,
      "latitude": "41.0000",
      "longitude": "-76.0000",
      "state_iso": "PA",
      "next_function": "v3/order/0000000000000000000000000000a002"
    }
  ]
}

الأخطاء

• 500: msg 'ISO Code parameter is required': المعامل isocode مفقود أو فارغ. هذا خطأ في الطلب يمكن تصحيحه. لا تُعيَّن حالة HTTP مطابقة.
• 404: msg 'Error: no such country': رمز البلد غير معروف. لا تُعيَّن حالة HTTP مطابقة.
• 404: msg 'State filter is only available for US and CA': أُرسل معامل state غير فارغ لبلد آخر. لا تُعيَّن حالة HTTP مطابقة.
• 404: msg 'Invalid state': قيمة state ليست رمزًا معروفًا ولا اسمًا معروفًا للبلد. لا تُعيَّن حالة HTTP مطابقة.
• 404: msg 'No areas found': لا تطابق أي منطقة مرشحات البلد والمصدر والولاية أو المقاطعة. لا تُعيَّن حالة HTTP مطابقة.
• 401: المصادقة غائبة أو فاشلة. تُرسل مع حالة HTTP 401.

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

• استعلام فقط لحسابات العملاء. لا يحجز أي شيء، ولا يقدّم طلب شراء، ولا يغيّر أي شيء.
• available معلومة استرشادية وقد تتغير قبل الخطوة التالية.