प्रमाणीकरण और API प्रतिक्रियाएँ

API क्रेडेंशियल्स का उपयोग करें

v3 अनुरोध HTTPS के माध्यम से इस पते पर भेजें https://api.multitel.net. इस मार्गदर्शिका में प्रत्येक एंडपॉइंट के लिए प्रमाणीकरण आवश्यक है. क्रेडेंशियल्स को अपने सर्वर पर रखें और उन्हें कभी भी ब्राउज़र JavaScript, सार्वजनिक पृष्ठों, स्क्रीनशॉट या स्रोत नियंत्रण में न रखें.

इनमें से किसी एक क्रेडेंशियल रूप का उपयोग करें:

• HTTP Basic API उपयोगकर्ता नाम और पासवर्ड के साथ, जो आपके MultiTEL खाते के लिए कॉन्फ़िगर किए गए हैं.
• Bearer टोकन एक Authorization: Bearer YOUR_API_TOKEN हेडर में, टोकन प्रमाणीकरण के लिए कॉन्फ़िगर किए गए सक्षम API खाते के लिए. टोकन अनुरोध केवल उस 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) कैटलॉग विवरण ताज़ा करता है और आपके खाते के लिए मूल्य-प्रस्ताव सहेजता है, लेकिन यह ऑर्डर नहीं करता है. कोई भी खोज अनुरोध नंबर आरक्षित नहीं करता है, और अनुरोधों के बीच इन्वेंट्री बदल सकती है. ऑर्डर करने वाले एंडपॉइंट का उपयोग करने से पहले किसी नंबर के लिए आवश्यकताओं और मूल्य की समीक्षा करें.

खरीद, असाइनमेंट, संदेश, फैक्स भेजने और अन्य कार्रवाइयों के लिए, उस एंडपॉइंट के अपने पुनः प्रयास नियमों का पालन करें. यदि किसी कार्रवाई का अनुरोध भेजने के बाद उत्तर की प्रतीक्षा का समय समाप्त हो जाए, तो उस कार्रवाई को दोहराने से पहले उसकी स्थिति या अपने खाता रिकॉर्ड जाँचें. खोई हुई प्रतिक्रिया यह साबित नहीं करती है कि कार्रवाई विफल हो गई थी.