किसी प्रीफ़िक्स से फ़ोन नंबर ऑर्डर करें

किसी प्रीफ़िक्स से ऑर्डर करें

इस ऑपरेशन का उपयोग तब करें जब प्रीफ़िक्स कैटलॉग आपको अलग-अलग उपलब्ध नंबर चुनने के बजाय किसी प्रीफ़िक्स से आवश्यक संख्या में नंबर ऑर्डर करने को कहे। शुरुआत इनके साथ करें: देश, क्षेत्र या राज्य, और प्रीफ़िक्स। प्रीफ़िक्स पहचानकर्ता और मूल्य योजना एक ही ताज़ा परिणाम से लें और सुरक्षित रखें। उपलब्ध नंबरों की सूची से चुने गए किसी विशेष नंबर के लिए इस विकल्प का उपयोग करें: चुना हुआ फ़ोन नंबर खरीदें।

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

खरीद का अनुरोध भेजें

अनुमत स्रोत IP पते से HTTPS के माध्यम से सक्षम API खाते का उपयोग करें। कैटलॉग में अपने वर्तमान चयन और अपनी स्वीकृत डिलीवरी कॉन्फ़िगरेशन के अनुसार वेरिएबल सेट करें। नीचे दिया गया कमांड एक नंबर खरीदता है।

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

ऊपर फ़ॉर्म POST दिखाया गया है। जब Content-Type का मान application/json होता है, तो समन्वयक JSON ऑब्जेक्ट भी पढ़ता है। JSON फ़ील्ड समान नाम वाले फ़ॉर्म/अनुरोध फ़ील्ड के मानों की जगह लेते हैं। लगातार एक ही एन्कोडिंग का उपयोग करें; क्वेरी और बॉडी में परस्पर विरोधी मान न भेजें।

डिलीवरी और नवीनीकरण की सेटिंग

वही डिलीवरी सेटिंग चुनें जो आप पोर्टल में उस नंबर के लिए उपयोग करेंगे। ये उन्नत कॉन्फ़िगरेशन मान हैं, Hosted PBX या ओरिजिनेशन ट्रंक बनाने के निर्देश नहीं। खाते की ऐसी कॉन्फ़िगरेशन का फिर से उपयोग करें जिसके काम करने की पुष्टि हो चुकी हो, और खरीद के बाद सहेजे गए नंबर की जाँच करें। केवल खरीद स्वीकार हो जाना इस बात की पुष्टि नहीं करता कि वॉइस या SMS डिलीवरी काम करती है।

इन फ़ील्ड को मानकीकृत करके चेकआउट को भेजा जाता है, लेकिन उपलब्ध नंबरों को खरीदने के अलग-अलग मार्गों में इन्हें स्थायी रूप से सहेजने का व्यवहार अलग होता है। वर्तमान ऑर्डर रूट, चुने हुए नंबर की खरीद मार्गदर्शिका में बताए गए कोटेशन की अधिकतम सीमा सख्ती से लागू करने वाले फ़ील्ड को समकक्ष सुरक्षा उपायों के रूप में उपलब्ध नहीं कराता। खाते की खरीद अनुमतियों और मूल्य सीमाओं का उपयोग करें तथा खरीद के बाद नंबर की कॉन्फ़िगरेशन जाँचें।

पूरा परिणाम पढ़ें

HTTP अनुरोध सफल होने पर भी JSON बॉडी पार्स करें और status.code तथा status.msg जाँचें। यह रूट अपनी JSON प्रतिक्रिया स्वयं लिखता है, और साझा प्रतिक्रिया सहायक भी आवश्यक रूप से एप्लिकेशन कोड को HTTP स्थिति से नहीं जोड़ता। एप्लिकेशन कोड JSON संख्याएँ या संख्यात्मक स्ट्रिंग हो सकते हैं। status.results की मौजूदगी अनिवार्य न मानें; यह सामान्य ऑर्डर परिणाम में मौजूद नहीं होता।

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

ऊपर दिए गए पहचानकर्ता, नंबर और कीमतें काल्पनिक हैं। ऑर्डर ID की आंतरिक संरचना से कोई अर्थ न निकालें। numbers उन नंबरों की सूची देता है जिन्हें यह प्रतिक्रिया खरीदा हुआ बताती है; इसकी लंबाई की तुलना अनुरोधित संख्या से करें। मूल्य राशियाँ स्ट्रिंग होती हैं और यह प्रतिक्रिया per_minute सहित मौद्रिक दरों को दशमलव के दो स्थानों तक पूर्णांकित करती है; दर की मूल परिशुद्धता के लिए ताज़ा कैटलॉग का उपयोग करें। शामिल मिनट और चैनल संख्यात्मक मानों या संख्यात्मक स्ट्रिंग के रूप में आ सकते हैं।

मूल्य खंड उस चुनी गई योजना का विवरण देता है जिसका उपयोग प्रतिक्रिया बनाने में हुआ है; यह हर नंबर का विस्तृत बिल या ऑर्डर की कुल राशि नहीं है। खरीद के लिए उपलब्ध अलग-अलग नंबरों की योजनाएँ अलग हो सकती हैं। इस खंड की राशि को गुणा करके उसे अंतिम कुल राशि का प्रमाण मानने के बजाय प्रत्येक खरीदे गए नंबर और खाते के लेनदेन का मिलान करें।

आंशिक खरीद और अनिश्चित परिणाम

एप्लिकेशन कोड 200 के साथ चेतावनी और अनुरोधित संख्या से कम नंबर मिल सकते हैं। बाद में होने वाली विफलता पहले से खरीदे गए नंबरों की खरीद रद्द नहीं करती। लौटाए गए ऑर्डर ID, नंबर और संदेश सुरक्षित रखें। शेष संख्या में नंबर ऑर्डर करने का निर्णय लेने से पहले उन नंबरों का अपनी नंबर सूची और खाते के लेनदेन से मिलान करें।

अनुरोध भेजने के बाद समयसीमा समाप्त होना, अनुरोध का कनेक्शन टूटना, गलत प्रारूप वाली प्रतिक्रिया या त्रुटि आना इस बात का प्रमाण नहीं है कि कुछ नहीं हुआ। उसी संदर्भ के साथ भी दूसरी खरीद का अनुरोध अपने आप न भेजें। मूल अनुरोध, संदर्भ और लौटाया गया कोई भी ऑर्डर ID सुरक्षित रखें, नंबर सूची और खाते के लेनदेन जाँचें, और परिणाम अनिश्चित रहने पर सहायता टीम से संपर्क करें।

अपुष्ट ऑर्डर एप्लिकेशन कोड 400 और ऐसा संदेश लौटा सकता है कि उसकी पुष्टि अभी जारी है। लौटाया गया ऑर्डर ID सुरक्षित रखें और उस खरीद का मिलान करें; यह उसे दोबारा भेजने का निर्देश नहीं है। दर्ज किए गए ऑर्डर की पुनर्प्राप्ति प्रक्रिया मूल ऑर्डर को आंतरिक रूप से ट्रैक करती है। इस ऑपरेशन को भेजा गया नया अनुरोध आपके संदर्भ के आधार पर पुराने ऑर्डर को फिर से जारी करने के बजाय खरीद का अलग प्रयास बनाता है, इसलिए इससे और नंबर खरीदे जा सकते हैं और उनका शुल्क लग सकता है। स्थिति जाँचने या उपलब्ध नंबर खोजने के लिए खरीद अनुरोध बार-बार न भेजें।

पंजीकरण और सक्रियण

खरीदे गए या आवंटित नंबर को अभी भी पंजीकरण या सक्रियण की आवश्यकता हो सकती है। यदि needs_registration का मान 1 है, तो restrictions और registration_requirements जाँचें। इनमें दूसरा फ़ील्ड इस एंडपॉइंट की पहचान कर सकता है: v3/get_requirements और इसके साथ country तथा number_type के मान दे सकता है। आने वाली कॉल या संदेशों पर निर्भर होने से पहले लागू पहचान/पते की प्रक्रिया पूरी करें और नंबर की स्थिति की पुष्टि करें।

features घोषित क्षमताओं का विवरण देता है; यह वास्तविक रूटिंग, अभियान की स्वीकृति, SMS डिलीवरी या फ़ैक्स प्राप्ति की पुष्टि नहीं करता। सहेजी गई डिलीवरी सेटिंग जाँचें और नंबर सक्रिय होने पर उपयुक्त सेवा परीक्षण करें।

ऑर्डर के कॉलबैक

कॉलबैक POST के माध्यम से JSON भेजते हैं जिसमें ऑर्डर की स्थिति और प्रतिक्रिया होती है तथा, यदि आपने संदर्भ दिया हो, तो वह भी जोड़ा जाता है। ये आंशिक परिणामों सहित उन खरीदों के लिए भेजे जाते हैं जिनकी सूचना दी गई है। कॉलबैक विफल होने से खरीद वापस नहीं होती। डिलीवरी का फिर से प्रयास हो सकता है, इसलिए दूसरी खरीद करने के बजाय ऑर्डर ID के आधार पर दोहराई गई सूचनाएँ संभालें और नंबरों का मिलान करें।

यह रूट कॉलबैक में क्रिप्टोग्राफ़िक हस्ताक्षर नहीं जोड़ता। कॉलबैक को प्रमाणीकरण के बाद प्राप्त अपनी नंबर सूची से मिलान करने की सूचना मानें, शुल्क लगाने, सेवा उपलब्ध कराने या पहुँच देने की स्वतंत्र अनुमति नहीं। कॉलबैक URL में API क्रेडेंशियल न डालें। अलग कॉलबैक URL के साथ दूसरी खरीद का अनुरोध भेजने से मूल ऑर्डर अपडेट नहीं होता; इससे खरीद का अलग प्रयास बनता है। सहायता टीम से किसी ऑर्डर के कॉलबैक की जाँच करवाते समय मूल ऑर्डर ID सुरक्षित रखें।

जिन विफलताओं को संभालना है