کسی ملک کے خصوصی نمبر کی اقسام اور قیمتوں کی فہرست حاصل کریں

مقامی نمبر تلاش کرنے کے لیے 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 کے ساتھ بھیجا جاتا ہے۔

دستیابی اور ضمنی اثرات

• کوئی آرڈر نہیں دیتا۔ اس اینڈ پوائنٹ کے کوڈ میں رقم وصول کرنے کا کوئی مرحلہ نظر نہیں آتا۔
• آپ کے اکاؤنٹ کے لیے کیٹلاگ کی تفصیلات اور قیمت کی پیشکشیں تازہ کرتا ہے، اور انہی منصوبوں کی سابقہ پیشکشوں کی جگہ نئی پیشکشیں محفوظ کرتا ہے۔ آرڈر دینے والے اینڈ پوائنٹس ان پیشکشوں کو کیسے استعمال کرتے ہیں، یہ الگ دستاویز میں بیان کیا گیا ہے۔
• قیمتیں آپ کے اکاؤنٹ کے لیے مخصوص ہوتی ہیں اور ان میں حسبِ ضرورت مقرر کردہ قیمتیں شامل ہو سکتی ہیں۔ جواب میں کرنسی نہیں بتائی جاتی۔
• کیٹلاگ میں براہ راست تلاش کرتا ہے، اس لیے معلومات تلاش کرنے والی دوسری کالز کے مقابلے میں زیادہ وقت لے سکتا ہے۔ مختلف کالز کے نتائج بدل سکتے ہیں۔