عرض الولايات الأمريكية أو المقاطعات الكندية التي تتوفر أرقام في مخزونها

استخدم هذه الخطوة الاختيارية للولايات المتحدة أو كندا لحصر البحث حسب الولاية أو المقاطعة. لا تُقبل إلا القيمتان US وCA.

• يصف كل عنصر البادئات المتوفرة في مخزون تلك الولاية وقت الطلب.
• اتبع الرابط next_function لعرض مناطق الولاية. يتضمن الرابط بالفعل مرشح state، لكنه لا يتضمن pid.
• تتم مطابقة معلومات الولاية بطريقة مختلفة قليلًا عند البحث عن المناطق. إذا أعاد رابط الولاية next_function النتيجة No areas found، فاستدعِ getareas دون تحديد ولاية بدلًا من ذلك.
• تحقق من status.code قبل قراءة response. عند تحديد بلد غير مدعوم أو بلد لا يوجد له مخزون مطابق، يُعاد الرمز 404 دون حالة HTTP مطابقة.
• وجود قائمة فارغة مع الرمز 200 يعني وجود مخزون، لكن دون معلومات عن الولاية. استدعِ getareas دون تحديد ولاية.

الطلب

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

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

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getstates/US'

الاستجابة

بنية الاستجابة القياسية. عند النجاح، تكون قيمة status.code هي 200، ويكون status.msg فارغًا، وتكون قيمة status.results هي عدد العناصر. response قائمة مرتبة حسب name (دون الاعتداد بحالة الأحرف)، ثم حسب رمز state. الحقول: state (رمز الولاية أو المقاطعة المأخوذ من بيانات الولاية الخاصة بالبادئات، ويتكون عادةً من حرفين؛ وتُمرر القيم غير المعتادة دون تغيير)؛ name (الاسم في الدليل، أو الرمز إذا لم يكن له اسم في الدليل)؛ country_iso؛ available (إجمالي المخزون عبر البادئات المحتسبة، ويكون دائمًا أكبر من 0)؛ prefix_count (عدد البادئات المتوفرة في المخزون التي تم احتسابها)؛ is_mobile (1 إذا كانت أي بادئة محتسبة تدعم خدمات الهاتف المحمول؛ وتكون القيمة دائمًا 0 بالنسبة إلى US ما لم يكن حسابك مفعّلًا للأرقام الأمريكية للهواتف المحمولة)؛ sms_coverage (1 إذا كانت أي بادئة محتسبة تتمتع بتغطية الرسائل النصية القصيرة)؛ returns_numbers (1 إذا كانت أي بادئة محتسبة تحمل مؤشر إرجاع الأرقام أو لم تكن لها قيمة لهذا المؤشر)؛ next_function ('v3/getareas/{isocode}?state={state}'). إذا وُجدت بادئات في المخزون ولكن لم تتضمن أي منها معلومات عن الولاية، تكون النتيجة status.code بقيمة 200 مع قائمة فارغة وstatus.results بقيمة 0.

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

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 2
  },
  "response": [
    {
      "state": "NY",
      "name": "New York",
      "country_iso": "US",
      "available": 120,
      "prefix_count": 8,
      "is_mobile": 0,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=NY"
    },
    {
      "state": "TX",
      "name": "Texas",
      "country_iso": "US",
      "available": 45,
      "prefix_count": 3,
      "is_mobile": 0,
      "sms_coverage": 0,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=TX"
    }
  ]
}

الأخطاء

• 500: msg 'ISO Code parameter is required': المعلمة isocode غير موجودة أو فارغة. هذا خطأ في الطلب يمكن تصحيحه. لا تُعيّن حالة HTTP مطابقة؛ اقرأ status.code.
• 404: msg 'getstates is only available for US and CA': عند استخدام أي رمز بلد آخر. لا تُعيّن حالة HTTP مطابقة.
• 404: msg 'No states found': لا توجد بادئات في المخزون تطابق مرشحي البلد والمصدر. لا تُعيّن حالة HTTP مطابقة.
• 401: المصادقة غير موجودة أو فشلت. تُرسل مع حالة HTTP 401.

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

• للاستعلام فقط. لا يحجز أي شيء ولا ينفذ أي طلب شراء ولا يغيّر أي شيء. الحقل available للمعلومات فقط ولا يحجز أرقامًا.