عرض أنواع الأرقام الخاصة وأسعارها لبلد معين

يمكن العثور على الأرقام المحلية باستخدام getcountries وgetareas. للأرقام الوطنية والمجانية والمشتركة التكلفة والعالمية وأرقام الجوال، استدعِ other مع رمز ISO الخاص بالبلد.

• تظهر المجموعات بترتيب ثابت، وتُحذف المجموعات التي لا تحتوي على إدخالات.
• يسرد كل إدخال خطط الأسعار الخاصة بحسابك في prices. اختر خطة بناءً على قيم channels، monthly_price، setup_price، per_minute وfree_minutes، واحتفظ بقيمة price_id الخاصة بها لاستخدامها عند الطلب إذا كانت نقطة النهاية المعنية تطلبها.
• إذا كانت قيمة needs_registration تُقيَّم منطقيًا إلى صواب، فاقرأ restrictions قبل تقديم الطلب. تعامل مع ذلك النص بوصفه محتوى عرض غير موثوق.
• اتبع next_function: v3/getnumbers/{uuid} يتيح لك اختيار رقم محدد، وv3/order/{uuid} يقدّم طلبًا من الإدخال مباشرةً.
• وجود قائمة response فارغة مع الرمز 200 يعني أنه لم يُعثر على أنواع أرقام خاصة وقت إرسال الطلب. إذا تعذّر الوصول إلى الكتالوج مؤقتًا، فقد تكون الاستجابة غير مكتملة أو لا تكون بصيغة JSON صالحة، لذا أعد المحاولة لاحقًا.
• تُرجع البلدان غير المدرجة في الكتالوج الرمز 404 دون حالة HTTP مطابقة. تحقّق دائمًا من status.code.

الطلب

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

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

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

الاستجابة

بنية الاستجابة القياسية. عند النجاح، تكون قيمة status.code هي 200، وتكون status.msg فارغة، وتكون status.results عدد المجموعات. response قائمة بالمجموعات. حقول المجموعة: group_key (مفتاح النوع بصيغة موحّدة: national، tollfree، sharedcost، global، mobile، أو مفتاح آخر مكوّن من أحرف صغيرة وأرقام)؛ group_name (اسم العرض)؛ group_type_uuid (معرّف نوع مُعتم)؛ items. تُرتّب المجموعات على النحو التالي: national، tollfree، sharedcost، global، mobile، ثم المفاتيح الأخرى بحسب group_name. تُحذف المجموعات التي لا تحتوي على items، ويُحذف النوع المحلي أيضًا. بالنسبة إلى US، تُحذف مجموعة الجوال ما لم يكن حسابك مفعّلًا لأرقام الجوال في US. تُرتّب العناصر بحسب name (دون التمييز بين الأحرف الكبيرة والصغيرة)، ثم بحسب prefix. حقول العنصر: uuid (معرّف إدخال مُعتم يُستخدم في next_function)؛ area_uuid (معرّف مُعتم لمجموعة الكتالوج)؛ country_uuid (معرّف بلد مُعتم)؛ prefix (البادئة الكاملة التي تبدأ بالعلامة '+' ورمز الاتصال الدولي للبلد)؛ name (الاسم في الكتالوج؛ قد تظهر علامات الاقتباس مسبوقة بشرطة مائلة عكسية للهروب)؛ metered وoverflow وneeds_registration (مؤشرات قد تكون من النوع boolean أو number؛ تعامل مع أي قيمة تُقيَّم منطقيًا إلى صواب على أنها نعم)؛ restrictions (فارغ عندما لا يلزم التسجيل، وإلا فهو نص المتطلبات الذي قد يتضمن فواصل أسطر HTML ورابطًا وعلامات اقتباس محيطة وأحرفًا مُفلَتة؛ تعامل معه بوصفه نص عرض غير موثوق)؛ state (بالنسبة إلى US وCA وPR، رمز ولاية أو قائمة فارغة عندما لا يُعرف أي رمز؛ وبالنسبة إلى البلدان الأخرى، رمز ISO الخاص بالبلد)؛ country_iso؛ is_mobile (1 في مجموعة الجوال، وإلا 0)؛ number_type (مطابق لـ group_key)؛ available (عدد من النوع integer يبلّغ عنه الكتالوج للإدخال، وتكون قيمته 0 عند عدم الإبلاغ عنه)؛ sms_coverage (1 إذا ذكرت أي ميزة SMS أو MMS)؛ returns_numbers (1 عندما يكون عرض أرقام محددة ممكنًا)؛ next_function ('v3/getnumbers/{uuid}' عندما تكون قيمة returns_numbers هي 1، وإلا 'v3/order/{uuid}')؛ prices؛ features (قائمة بسلاسل نصية تصف الإمكانات)؛ group_key؛ group_type_uuid. يحتوي كل إدخال في prices على price_id (معرّف خطة مُعتم)، وis_customer_custom (true عند انطباق تسعير مخصص لحسابك؛ وذلك فقط للخطط التي لا تتضمن قنوات مشمولة)، وper_minute وfree_minutes (سلاسل نصية لأعداد عشرية)، وsetup_price وmonthly_price (سلاسل نصية بمنزلتين عشريتين)، وchannels (عدد القنوات المشمولة، من النوع integer). تُحذف الإدخالات التي لا تحتوي على أي خطة أسعار. يُنظر في ما لا يزيد على 1000 إدخال من الكتالوج لكل نوع أرقام في كل طلب. إذا لم يحتوِ أي نوع على إدخالات، تكون response قائمة فارغة وتكون قيمة status.results هي 0. إذا فشل البحث المباشر في الكتالوج، فقد لا تستخدم الاستجابة هذه البنية، أو قد تكون بعض المجموعات مفقودة.

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

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "group_key": "tollfree",
      "group_name": "Toll-free",
      "group_type_uuid": "00000000-0000-4000-8000-0000000000a1",
      "items": [
        {
          "uuid": "0000000000000000000000000000b001",
          "area_uuid": "0000000000000000000000000000a001",
          "country_uuid": "0000000000000000000000000000c001",
          "prefix": "+33800",
          "name": "Example Toll-free",
          "metered": true,
          "overflow": 0,
          "needs_registration": 0,
          "restrictions": "",
          "state": "FR",
          "country_iso": "FR",
          "is_mobile": 0,
          "number_type": "tollfree",
          "available": 10,
          "sms_coverage": 0,
          "returns_numbers": 1,
          "next_function": "v3/getnumbers/0000000000000000000000000000b001",
          "prices": [
            {
              "price_id": "0000000000000000000000000000d001",
              "is_customer_custom": false,
              "per_minute": "0.05",
              "free_minutes": "0",
              "setup_price": "0.00",
              "monthly_price": "5.00",
              "channels": 2
            }
          ],
          "features": ["voice"],
          "group_key": "tollfree",
          "group_type_uuid": "00000000-0000-4000-8000-0000000000a1"
        }
      ]
    }
  ]
}

الأخطاء

• 500: msg 'ISO Code parameter is required': المعلمة isocode مفقودة أو فارغة. هذا خطأ في الطلب يمكن تصحيحه. لا تُعيَّن حالة HTTP مطابقة.
• 404: msg 'Error: no such country': البلد غير معروف أو غير مرتبط بكتالوج الأرقام الخاصة. لا تُعيَّن حالة HTTP مطابقة.
• 401: المصادقة مفقودة أو فاشلة. تُرسل مع حالة HTTP 401.

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

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