تصدیق اور API جوابات

API اسناد استعمال کریں

v3 درخواستیں HTTPS کے ذریعے https://api.multitel.net کو بھیجیں. اس رہنما میں ہر اختتامی نقطہ کو توثیق درکار ہے. اسناد اپنے سرور پر رکھیں, اور انہیں کبھی براؤزر JavaScript, عوامی صفحات, اسکرین شاٹس یا سورس کنٹرول میں نہ ڈالیں.

ان میں سے ایک اسنادی شکل استعمال کریں:

• HTTP Basic API صارف نام اور پاس ورڈ کے ساتھ جو آپ کے MultiTEL اکاؤنٹ کے لیے مرتب کیے گئے ہیں۔
• Bearer ٹوکن کو Authorization: Bearer YOUR_API_TOKEN والے ہیڈر میں بھیجیں، ایک فعال API اکاؤنٹ کے لیے جو ٹوکن تصدیق کے لیے مرتب کیا گیا ہے. ٹوکن درخواستیں صرف اسی اکاؤنٹ کے لیے اجازت شدہ پتوں سے قبول کی جاتی ہیں.

اگر IP اجازت فہرست آپ کے API اکاؤنٹ کے لیے مرتب کی گئی ہے, تو تمام درخواستیں اجازت شدہ پتوں سے بھیجیں.

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

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

ان مثالوں میں متغیرات ان اسناد کے لیے جگہ گیر ہیں جو آپ اپنے ماحول میں نجی طور پر رکھتے ہیں.

تصدیق کی ناکامیوں سے نمٹیں

تصدیق کی ناکامیاں HTTP اسٹیٹس 401 کے ساتھ بھیجی جاتی ہیں۔ باڈی معیاری لفافہ استعمال کرتی ہے، جس میں status.code کی قدر 401 ہے اور فیلڈ response میں خالی سٹرنگ ہوتی ہے۔

• کوئی اسناد نہیں: status.msg کی قدر Username and password are required ہے، اور جواب میں Basic تصدیقی چیلنج شامل ہے.
• Bearer ٹوکن مسترد: اگر Authorization ہیڈر Bearer اسکیم استعمال کرتا ہے اور ٹوکن نامعلوم, غیر فعال یا آپ کے پتے سے اجازت شدہ نہیں ہے, status.msg کی قدر Invalid bearer token ہے۔ جب Bearer ہیڈر موجود ہو تو کوئی دیگر اسناد آزمائی نہیں جاتیں.
• غلط Basic اسناد: status.msg کا آغاز A valid username and password pair are required. سے ہوتا ہے، اور جواب میں Basic تصدیقی چیلنج شامل ہے۔ پیغام میں مزید تشخیصی متن ہو سکتا ہے، اس لیے اسے پروگرام کے ذریعے پارس نہ کریں۔

انہی اسناد کے ساتھ خودکار طور پر دوبارہ کوشش نہ کریں. ایک پتے سے مختصر مدت میں بہت سی ناکام کوششیں اس پتے سے مزید درخواستوں کو مسدود کر سکتی ہیں.

رسپانس باڈی پڑھیں

زیادہ تر v3 اختتامی نقاط, بشمول getcountries, getstates, getareas اور other, اس لفافے میں JSON واپس کرتے ہیں:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

یہ مثالی ملک فہرست جواب ہے, موجودہ انوینٹری یا صلاحیتوں کا بیان نہیں ہے.

غلطی کا جواب اس طرح نظر آتا ہے:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

اگر جواب کو انکوڈ نہیں کیا جا سکتا, تو باڈی میں status.code 500, status.msg Response encoding error, اور خالی آبجیکٹ بطور response موجود ہوتے ہیں۔

پرانا اختتامی نقطہ GET /v3/countries اس کے بجائے {"code": 200, "data": [...]} واپس کرتا ہے۔ ہر اختتامی نقطے کا دستاویزی جواب چیک کریں۔ اگر باڈی درست JSON نہیں ہے، مثال کے طور پر غیر متوقع سرور ناکامی کے بعد، تو درخواست کو ناکام سمجھیں اور بعد میں دوبارہ کوشش کریں۔

API نتیجہ کوڈز اور HTTP اسٹیٹس

status.code API نتیجہ کوڈ ہے۔ یہ HTTP اسٹیٹس نہیں ہے۔ تصدیق کی ناکامیاں HTTP 401 کے ساتھ بھیجی جاتی ہیں۔ بصورت دیگر، دریافت کے اختتامی نقاط مثال کے طور پر 404 اور 500 صرف status.code میں رپورٹ کرتے ہیں اور مماثل HTTP اسٹیٹس مقرر نہیں کرتے۔ اس لیے کسی چیز کے نہ ملنے یا پیرامیٹر کے غائب ہونے کا نتیجہ کامیاب HTTP اسٹیٹس کے ساتھ بھی آ سکتا ہے۔ status.code کو چیک کیے بغیر response استعمال نہ کریں۔

نتیجہ کوڈ 500 کے ساتھ پیغام ISO Code parameter is required آنے کا مطلب ہے کہ مطلوبہ پیرامیٹر غائب ہے. اسے سرور بندش سمجھنے کے بجائے درخواست درست کریں.

next_function پر عمل کریں

دریافت کے نتائج میں next_function شامل ہوتا ہے۔ یہ بغیر ابتدائی سلیش کے نسبتی راستہ ہے, کبھی کبھی استفسار سٹرنگ کے ساتھ, جیسے v3/getareas/US یا v3/getareas/US?state=NY. اس سے پہلے https://api.multitel.net/ لگائیں تاکہ اگلی درخواست بنائی جا سکے، اور اس درخواست کی اسی طرح تصدیق کریں۔ اختیاری فلٹرز جو آپ نے بھیجے، جیسے pid، next_function میں منتقل نہیں کیے جاتے۔ اگر آپ کو ان کی ضرورت ہو تو انہیں دوبارہ شامل کریں۔

اختیاری انوینٹری سلیکٹر (pid)

getcountries, getstates اور getareas ایک اختیاری استفسار پیرامیٹر pid قبول کرتے ہیں، جو نتائج کو ایک انوینٹری ماخذ تک محدود کرتا ہے۔ اسے صرف MultiTEL کی فراہم کردہ قدر کے ساتھ استعمال کریں، یا تو اس کی عددی شکل میں یا اس کی 32 حروف والی ہیکساڈیسیمل شکل میں۔ عام استعمال کے لیے اسے چھوڑ دیں۔ pid استفسار سٹرنگ میں بھیجیں۔ اگر اختتامی نقطہ قدر کو نہیں پہچانتا یا قبول نہیں کرتا, تو وہ اسے بغیر غلطی کے نظر انداز کرتا ہے, اور درخواست اس طرح برتاؤ کرتی ہے جیسے pid چھوڑ دیا گیا تھا.

دریافت کو آرڈرز سے الگ کریں

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

خریداریوں, تفویضات, پیغامات, فیکس بھیجنے اور دیگر اعمال کے لیے, اس اختتامی نقطہ کے اپنے دوبارہ کوشش قوانین پر عمل کریں. اگر کسی عمل کی درخواست بھیجنے کے بعد انتظار کا وقت ختم ہو جائے، تو دوبارہ درخواست بھیجنے سے پہلے عمل کا اسٹیٹس یا اپنے اکاؤنٹ کے ریکارڈز چیک کریں۔ کھویا ہوا جواب ثابت نہیں کرتا کہ عمل ناکام ہوا.