Telserv से Bird पर माइग्रेट करें

यह गाइड उन इंटीग्रेशन के लिए है जो नंबर खरीदने, रूट करने और रिलीज़ करने के लिए Telserv पार्टनर API (V1 या V2) को कॉल करते हैं, और अब Bird API पर जा रहे हैं।

Bird API हर Bird उत्पाद को सेवा देता है, इसलिए इसके नंबर और वॉइस ऑपरेशन Telserv के बजाय Bird के अपने नियमों का पालन करते हैं। आपका इंटीग्रेशन जिन क्षमताओं का उपयोग करता है, उनमें से अधिकांश के लिए एक Bird कॉल है। एंडपॉइंट, पेलोड, पहचानकर्ता और ऑथेंटिकेशन अलग हैं, इसलिए इंटीग्रेशन को दोबारा लिखने की योजना बनाएँ। जहाँ Bird कोई काम अलग तरीके से करता है, वहाँ यह गाइड बताती है कि कैसे।

यह गाइड अभी तैयार हो रही है। इसमें वह शामिल है जो Bird करता है, और माइग्रेशन के साथ यह बढ़ती जाती है। यदि आपका उपयोग किया जाने वाला कोई Telserv ऑपरेशन यहाँ सूचीबद्ध नहीं है, तो उसे जोड़ने से पहले उसका दायरा तय करना और उस पर काम करना बाकी है; इसके बारे में अपने माइग्रेशन संपर्क से पूछें।

शुरू करने से पहले

• पूर्ण पहचान सत्यापन वाला एक Bird संगठन, जो पहली नंबर खरीद के लिए आवश्यक है।
• एक API कुंजी, जिसमें वे स्कोप हों जिनका उपयोग उदाहरण करते हैं: नंबरों और ऑर्डरों के लिए write स्तर पर numbers, स्वामित्व के कागज़ात वाले स्वतंत्र ऑपरेशनों के लिए write स्तर पर compliance, और SIP ट्रंक, वॉइस नंबरों और सत्यापित नंबरों के लिए write स्तर पर voice_management। टेस्ट कॉल के लिए voice:write भी चाहिए, और कॉल लेग पढ़ने के लिए voice:read चाहिए।
• वॉलेट बैलेंस। ऑर्डरों का भुगतान वॉलेट से होता है। जब कोई ऑर्डर अस्वीकार हो में 402 और 412 अस्वीकृतियों के बारे में बताया गया है।

Telserv में आपका इंटीग्रेशन जिन नंबरों को प्रबंधित करता है, उन्हें दोबारा खरीदने की ज़रूरत नहीं है। आपके नंबर आपके Bird वर्कस्पेस में ले जाए जाने के बाद वे GET /v1/numbers में दिखते हैं। यह कब होता है, इसकी पुष्टि आपका माइग्रेशन संपर्क करता है। ले जाए गए नंबर का nda_ पहचानकर्ता पाने के लिए, देश कोड सहित अंक देकर GET /v1/numbers?number=<digits> से उसे खोजें, और id को NUMBER_ID के रूप में रखें।

उदाहरण आपकी कुंजी BIRD_API_KEY से और उसका क्षेत्रीय होस्ट BIRD_API_URL से पढ़ते हैं: bk_eu1_ कुंजी के लिए https://eu1.platform.bird.com, या bk_us1_ कुंजी के लिए https://us1.platform.bird.com। अन्य वेरिएबल, जैसे TRUNK_ID और NUMBER_ID, किसी पिछली प्रतिक्रिया से मिला पहचानकर्ता रखते हैं; हर चरण बताता है कि वह कौन-सा वेरिएबल सेट करता है।

अनुबंध में क्या बदलता है

Bird API किसी अपरिचित क्वेरी पैरामीटर को 422 और E01029 के साथ अस्वीकार करता है। city जैसे केवल Telserv वाले फ़िल्टर आगे भेजने के बजाय अपने अनुरोधों से हटा दें।

एक नंबर के दो पहचानकर्ता

आपके वर्कस्पेस को आवंटित वॉइस-सक्षम नंबर के दो रिकॉर्ड होते हैं, और हर रिकॉर्ड का अपना पहचानकर्ता होता है:

• आवंटन, जो GET /v1/numbers से मिलता है। समर्पित नंबर के लिए इसका id nda_ से शुरू होता है और साझा नंबर के लिए nal_ से, और ऑर्डर का number_id उस नंबर का nda_ पहचानकर्ता है जिसे ऑर्डर ने खरीदा। नंबर को पढ़ने, नाम देने और संदर्भित करने के लिए, और समर्पित नंबर को रिलीज़ करने के लिए इसका उपयोग करें।
• वॉइस रिकॉर्ड, vnu_, जो GET /v1/voice/numbers से मिलता है। नंबर की आने वाली कॉल कहाँ जाती हैं, यह पढ़ने और बदलने के लिए इसका उपयोग करें। जिस नंबर में वॉइस क्षमता नहीं है, जैसे केवल SMS वाला नंबर, उसका कोई वॉइस रिकॉर्ड नहीं होता।

वॉइस ऑपरेशन nda_ या nal_ पहचानकर्ता को 422 के साथ अस्वीकार करते हैं। किसी नंबर का वॉइस रिकॉर्ड खोजने के लिए, search को नंबर के अंकों पर सेट करके वॉइस नंबरों की सूची लें, और वह प्रविष्टि चुनें जिसका provider.number_id आवंटन के id के बराबर है। किसी नंबर को अपने SIP ट्रंक पर रूट करें में अनुरोध दिखाया गया है, और अपने फ़ोन नंबर प्रबंधित करना में यह खोज समझाई गई है।

Telserv का GET /numbers/{dnisId} Bird में दो रीड बन जाता है: स्थिति और स्वामित्व के कागज़ात के लिए आवंटन, और रूट के लिए वॉइस रिकॉर्ड।

Telserv ऑपरेशनों को Bird से मैप करें

हर तालिका में एक काम, उसे करने वाली Telserv कॉल, और अब उसे करने वाली Bird कॉल दी गई है। हर तालिका के नीचे के नोट बताते हैं कि अनुरोध या प्रतिक्रिया में क्या बदलता है।

खरीदारी

• खोज। country_code आवश्यक है, इसलिए एक खोज एक ही देश को कवर करती है। prefix में देश कोड के बाद के राष्ट्रीय अंक दिए जाते हैं: Telserv का prefix=3170 अब country_code=NL&prefix=70 बन जाता है। एरिया कोड के आधार पर परिणाम सीमित करने के लिए city की जगह prefix का उपयोग करें, और productId की जगह number_type और capabilities का उपयोग करें।
• खोज परिणामों में कागज़ी कार्रवाई। हर परिणाम में excludeNumbersRequireVerification फ़िल्टर की जगह ownership_registration_required होता है। true मान का अर्थ है कि नंबर का बिल खरीद के समय से बनता है, लेकिन उसके कागज़ात स्वीकृत होने तक वह कोई SMS नहीं भेजता और उस पर कोई आने वाली या जाने वाली वॉइस कॉल नहीं होती।
• एक नंबर जाँचें। इसे इसके E.164 नंबर से संबोधित किया जाता है।
• कीमतें। Telserv किसी नंबर और किसी प्रोडक्ट के विस्तृत रीड पर pricing.staticPricing लौटाता था। Bird में हर खोज परिणाम pricing में आपके संगठन के लिए अपनी कीमत देता है: nrc की जगह setup_price, और mrc की जगह प्रति recurring_period recurring_price, साथ में intervals_per_charge, जो बताता है कि एक शुल्क कितनी अवधियों का बिल बनाता है। अपने रेफ़रेंस के साथ नंबर खोजें और खरीदें में कीमत वाले फ़ील्ड समझाए गए हैं।
• खरीदें। number और एक वैकल्पिक reference भेजें। ऑर्डर का भुगतान आपके वॉलेट से होता है। ज़्यादातर ऑर्डर 201 लौटाते हैं; जो ऑर्डर किसी कैरियर की प्रतीक्षा करता है वह 202 लौटाता है, और आपको उसकी स्थिति बार-बार जाँचनी होती है।
• सुरक्षित करें। नंबर ऑर्डर करने से वह सुरक्षित हो जाता है। पहले किसी संभावित नंबर को जाँचें, फिर उसे ऑर्डर करें।

नंबर

• सूची। सूची में वे नंबर होते हैं जो इस समय आपको आवंटित हैं। Bird में ऑर्डर किया गया कोई रिलीज़ हो चुका नंबर GET /v1/numbers/orders में अपने ऑर्डर के ज़रिए दिखता रहता है। अपने नंबरों का मिलान करें में फ़िल्टरों की मैपिंग दी गई है।
• पढ़ना। स्थिति, स्वामित्व के कागज़ात और कीमत आवंटन पर होते हैं, और रूट वॉइस रिकॉर्ड पर होता है। आवंटन का pricing ऑब्जेक्ट, जिसमें हर recurring_period के लिए recurring_price और intervals_per_charge होते हैं, pricing.staticPricing.mrc की जगह लेता है, और यह सूची में भी मिलता है, जबकि Telserv के GET /numbers में ऐसा नहीं था।
• बदलना। name और reference आवंटन पर होते हैं, और रूट वॉइस रिकॉर्ड पर होता है। फ़ोर्स्ड कोडेक और एक साथ चलने वाली कॉल की सीमा अपने SIP उपकरण पर सेट करें। destinationDistributionType, SIP ट्रंक पर गेटवे का priority बन जाता है: FailOver हर गेटवे को अलग priority देता है, और RoundRobin सभी को एक ही देता है।
• रिलीज़ करना। DELETE नंबर को उस अवधि के अंत तक रखता है जिसका भुगतान आप कर चुके हैं, और फिर उसे रिलीज़ करता है। POST …/release उसे तुरंत रिलीज़ करता है। इनमें से कोई भी तारीख नहीं लेता। नंबर रिलीज़ करें में दोनों अनुरोध दिखाए गए हैं।

डेस्टिनेशन और प्रोफ़ाइल

• SIP उपकरण। गेटवे ट्रंक का हिस्सा होता है और उस पर रूट किए गए हर नंबर को सेवा देता है, इसलिए जिन नंबरों को अलग-अलग डेस्टिनेशन सूचियाँ चाहिए, उन्हें अलग-अलग ट्रंक चाहिए। sortOrder अब priority बन जाता है। रिंग समय और समय-सीमाएँ अपने SIP उपकरण पर लागू करें।
• फ़ॉरवर्ड करें। forward_to और forward_as सेट करें। forward_to आपके सत्यापित नंबरों में से एक होना चाहिए; असत्यापित नंबर होने पर जवाब 412 और E21053 होता है। forward_as तय करता है कि फ़ॉरवर्ड की गई कॉल कॉलर के रूप में कौन-सा नंबर दिखाए। किसी नंबर का एक समय में एक ही रूट होता है, इसलिए SIP उपकरण से फ़ोन नंबर पर फ़ॉलबैक के लिए कॉल को अपने SIP उपकरण से फ़ॉरवर्ड करें।
• कॉल लेना बंद करें। जब तक आप नंबर को फिर से रूट नहीं करते, नंबर कॉल अस्वीकार करता है। डिफ़ॉल्ट प्रोफ़ाइल की जगह एक स्थायी डिफ़ॉल्ट बनाए रखने के लिए, नंबर को ऐसे ट्रंक पर रूट करें जिसमें आपके डिफ़ॉल्ट गेटवे हों।
• प्रोफ़ाइल। distributionType अब priority बन जाता है: FailOver हर गेटवे को अलग priority देता है, और RoundRobin सभी को एक ही देता है। वितरण हर ट्रंक के लिए सेट होता है, इसलिए जिन नंबरों को अलग वितरण चाहिए, उन्हें अलग ट्रंक चाहिए। {dnis} प्लेसहोल्डर destination_format में {number} बन जाता है, और prefixCLIP origination_format में {number} से पहले का टेक्स्ट बन जाता है।
• प्रोफ़ाइल लागू करें। ट्रंक को उसके spt_ पहचानकर्ता से संबोधित किया जाता है, जबकि Telserv प्रोफ़ाइल को नाम से संबोधित करता था।

दस्तावेज़ और अंतिम-उपयोगकर्ता डेटा

• आवश्यकताएँ। Telserv की शर्तों की सूची एक साथ हर प्रोडक्ट को कवर करती थी; Bird एक समय में एक फ़ॉर्म पढ़ता है। किसी एक नंबर की आवश्यकताएँ subject_kind=number, subject_id के रूप में उसके nda_ पहचानकर्ता और उसके country_code के साथ माँगें, या खरीदने से पहले program को नंबर प्रकार पर सेट करके और बिना subject_id के कोई फ़ॉर्म पढ़ें। fields की हर प्रविष्टि किसी Telserv शर्त या अंतिम-उपयोगकर्ता लेबल की जगह लेती है: उसका key वह है जिसके अंतर्गत आप उत्तर देते हैं, और data_type document उस प्रविष्टि को चिह्नित करता है जिसमें फ़ाइल चाहिए।
• दस्तावेज़। base64 fileContent की जगह फ़ाइल को multipart/form-data के रूप में अपलोड करें; हर दस्तावेज़ अपलोड करें में स्वीकृत फ़ाइलों की सूची है। एक ही फ़ाइल दो बार अपलोड करने पर वही अटैचमेंट मिलता है। केवल अपलोड करने से कुछ जमा नहीं होता: जमा वह सबमिशन करता है जो उसके attachment_id का हवाला देता है।
• अंतिम-उपयोगकर्ता डेटा और दस्तावेज़ एक साथ। Telserv हर दस्तावेज़ अलग कॉल में लेता था, और अंतिम-उपयोगकर्ता डेटा को दूसरी कॉल में लेबल की एक सूची के रूप में। Bird हर उत्तर, टाइप किया हुआ और दस्तावेज़ दोनों, एक ही सबमिशन में लेता है, और कोई ड्राफ़्ट नहीं होता: अनुरोध उत्तरों को समीक्षा के लिए जमा कर देता है। इसके बाद ownership.next का पालन करें, जो सुधार के लिए resupply बताता है और नया सबमिशन केवल ज़रूरत होने पर (हर उत्तर जमा करें)।
• बदलाव। केवल वे उत्तर भेजें जिन्हें आप बदल रहे हैं, बाकी उत्तरों की समीक्षा बनी रहती है। Telserv नंबर के सत्यापन लंबित रहने तक किसी शर्त के लिए नई फ़ाइल लेता था, और वह फ़ाइल उस शर्त की समीक्षा फिर से शुरू कर देती थी; Bird ऐसा उत्तर बदलता है जो अस्वीकृत, समाप्त या अभी तक नहीं दिया गया हो, और समीक्षाधीन या पहले से स्वीकृत उत्तर को अस्वीकार करता है, सिवाय उस उत्तर के जिसे editable_for_verifier_repair चिह्नित किया गया हो, जब तक हमारा माँगा गया सुधार खुला है (अस्वीकृत उत्तर सुधारें)।
• प्रगति। ownership.status और ownership.next बताते हैं कि नंबर किस स्थिति में है। हर उत्तर का अपना state होता है, और अस्वीकृत उत्तर में समीक्षक का reason होता है। Bird हर परिणाम आपके संगठन के मालिकों को और उस व्यक्ति को ईमेल भी करता है जिसने सबमिशन को आख़िरी बार जमा या सुधारा। जब नंबर के लिए कागज़ात ज़रूरी नहीं होते, तो ownership आमतौर पर null होता है।

स्वामित्व के कागज़ात जमा करें में अनुरोध दिखाए गए हैं, और किसी नंबर के स्वामित्व के कागज़ात जमा करें में पूरी प्रक्रिया समझाई गई है, जिसमें डैशबोर्ड से और ऑर्डर के साथ कागज़ात जमा करना भी शामिल है।

प्रोडक्ट और मास्टर डेटा

हर खोज परिणाम अपने प्रोडक्ट का विवरण number_type, capabilities और ownership_registration_required से देता है, और प्रोडक्ट के pricing.staticPricing (nrc और mrc) की जगह आपके संगठन के लिए कीमत देता है। Bird की मानक कीमतें फ़ोन नंबर मूल्य निर्धारण पेज पर हैं। Telserv के प्रति-मिनट sessionPricing का इन रीड में कोई समकक्ष नहीं है; वॉइस दरें वॉइस मूल्य निर्धारण पेज पर हैं।

Telserv के नंबर प्रकार Bird के number_type से इस तरह मेल खाते हैं:

क्या अलग तरीके से काम करता है

Telserv के ये काम Bird में अलग तरीके से होते हैं। अगर आपका इंटीग्रेशन इनमें से किसी पर निर्भर है, तो उसे ले जाने से पहले इनकी योजना बनाएँ।

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

अपने रेफ़रेंस के साथ नंबर खोजें और खरीदें

एक देश में खोजें। परिणामों को सीमित करने के लिए number_type, capabilities और prefix को मिलाकर इस्तेमाल करें:

curl "$BIRD_API_URL/v1/numbers/available?country_code=NL&number_type=mobile&capabilities=voice&limit=10" \
  --header "Authorization: Bearer $BIRD_API_KEY"

हर परिणाम में एक pricing ऑब्जेक्ट होता है, जिसमें वह कीमत होती है जो आपका संगठन नंबर के लिए चुकाता है। यह कीमत टैक्स के बिना, आपकी बिलिंग मुद्रा में होती है, और इसमें Bird के साथ तय की गई कोई भी कीमत लागू होती है:

• setup_price नंबर ऑर्डर करते समय एक बार लिया जाता है। शून्य के प्रकाशित शुल्क का amount "0" होता है। यह फ़ील्ड स्वयं तब null होता है जब कोई सेटअप शुल्क लागू नहीं होता, और तब भी जब recurring_price का मान null होता है, क्योंकि उस नंबर को ऑर्डर नहीं किया जा सकता।
• recurring_price प्रति recurring_period दर है।
• intervals_per_charge बताता है कि एक शुल्क में कितने recurring_period का बिल बनता है। टैक्स से पहले आवर्ती शुल्क recurring_price गुणा intervals_per_charge होता है, जो नंबर के आपके वर्कस्पेस को असाइन होने पर और हर नवीनीकरण पर लिया जाता है; सेटअप शुल्क अलग होता है। जो ऑर्डर किसी कैरियर की प्रतीक्षा करता है, उसके लिए असाइनमेंट ऑर्डर पूरा होने पर होता है।

API संदर्भ में एक उदाहरण परिणाम दिखाया गया है। pricing.recurring_price: null वाला परिणाम कोई आवर्ती कीमत नहीं बताता। ऑर्डर करने से पहले उस देश और नंबर प्रकार की कीमत तय करवाने के लिए सेल्स से संपर्क करें।

डैशबोर्ड और API एक ही संगठन कीमत का उपयोग करते हैं, जिसमें आपकी बिलिंग मुद्रा में रूपांतरण भी शामिल है। कीमत पढ़ने से कोटेशन तय नहीं होता: बाद के शुल्क से पहले टैरिफ़ या विनिमय दर बदलने पर उसकी राशि बदल सकती है। अगर कीमत की खोज विफल होती है, तो खोज E14009 के साथ 503 लौटाती है। एक्सपोनेंशियल बैकऑफ़ के साथ रीड के लिए फिर से प्रयास करें; खोज विफल होने का मतलब कभी यह नहीं होता कि नंबर की कोई कीमत नहीं है।

ऑर्डर करने से पहले किसी संभावित नंबर और उसकी कीमत की पुष्टि के लिए उसे GET /v1/numbers/available/{number} से पढ़ें। 404 का मतलब है कि वह अब बिक्री के लिए उपलब्ध नहीं है।

नंबर को उसी रेफ़रेंस के साथ ऑर्डर करें जो आपने Telserv में इस्तेमाल किया था, और एक idempotency कुंजी चुनें जिसे आप इस खरीद के हर फिर से प्रयास के लिए रखें:

curl --request POST "$BIRD_API_URL/v1/numbers/orders" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-CUST-778812" \
  --data '{"number": "+31612345678", "reference": "CUST-778812"}'

201 प्रतिक्रिया में status: completed और एक number_id होता है, जो नंबर का nda_ पहचानकर्ता है। इसे NUMBER_ID के रूप में रखें। 202 प्रतिक्रिया का मतलब है कि ऑर्डर किसी कैरियर का इंतज़ार कर रहा है: ऑर्डर को पोल करें जब तक उसका status completed या failed न हो जाए। अगर ऑर्डर बाद में विफल हो जाता है, तो पहले से लिया गया सेटअप शुल्क वापस नहीं होता। ऑर्डर पूरा होने पर रेफ़रेंस नंबर पर सेट हो जाता है। इसमें 100 वर्ण तक हो सकते हैं और इसका अद्वितीय होना ज़रूरी नहीं है।

आपके वर्कस्पेस को आवंटित नंबर के ऑर्डर का फिर से प्रयास करने पर मौजूदा ऑर्डर लौटता है, इसलिए फिर से प्रयास करने पर दो बार शुल्क नहीं लगता। नंबर खरीदें और रिलीज़ करें में अस्वीकृतियों के बारे में बताया गया है।

बाद में रेफ़रेंस सेट करने या बदलने के लिए PATCH /v1/numbers/{number_id} पर reference (और वैकल्पिक रूप से name) भेजें। किसी फ़ील्ड को खाली करने के लिए null भेजें।

जाँचें कि नंबर कॉल ले जा सकता है

जिस नंबर का status pending_ownership_registration है, वह आवंटित है और उसका बिल बनता है, लेकिन जब तक उसके स्वामित्व के कागज़ात स्वीकृत नहीं होते, वह कोई SMS नहीं भेजता और आने वाली और जाने वाली वॉइस कॉल अस्वीकार करता है। किसी नंबर को रूट करने या उस पर टेस्ट कॉल करने से पहले उसे GET /v1/numbers/{number_id} से पढ़ें और जाँचें कि status active है। अगर यह लंबित है, तो स्वामित्व के कागज़ात जमा करें। आवंटित नंबर की स्थिति में हर मान समझाया गया है।

नीचे दिए गए उदाहरण एक डच मोबाइल नंबर का उपयोग करते हैं। अपने नंबर का status भी इसी तरह जाँचें, चाहे वह किसी भी देश का हो।

स्वामित्व के कागज़ात जमा करें

Telserv किसी नंबर के कागज़ात हर दस्तावेज़ के लिए एक POST /numbers/{dnisId}/documents और सभी लेबल के लिए एक POST /numbers/{dnisId}/enduserdata से लेता था। Bird दस्तावेज़ अपलोड करने के बाद दोनों को एक ही सबमिशन में लेता है।

1. नंबर का country_code पढ़ें और उसे COUNTRY_CODE के रूप में रखें। कमांड इसे jq से निकालती है; अगर आप jq का उपयोग नहीं करते, तो इसे स्वयं पढ़ें:

   कोड उदाहरण

   COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code)

2. पढ़ें कि नंबर का देश क्या माँगता है। fields की हर प्रविष्टि में वह key होता है जिसके अंतर्गत आप उत्तर देते हैं, एक data_type, और required, जो बताता है कि उत्तर देना ज़रूरी है या नहीं। प्रतिक्रिया में दिया गया program PROGRAM के रूप में रखें:

   कोड उदाहरण

   curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \
     --header "Authorization: Bearer $BIRD_API_KEY"

   E19001 के साथ 422 का अर्थ है कि उस देश के लिए स्वामित्व का कोई फ़ॉर्म नहीं है।

3. हर वह दस्तावेज़ अपलोड करें जो कोई document फ़ील्ड माँगता है, base64 fileContent के बजाय फ़ाइल के रूप में। प्रतिक्रिया से id, यानी अटैचमेंट का tca_ पहचानकर्ता, ATTACHMENT_ID के रूप में रखें:

   कोड उदाहरण

   curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --form "file=@registration-certificate.pdf"

4. सभी उत्तर एक साथ जमा करें: हर उस फ़ील्ड के लिए एक प्रविष्टि जिसका required true है, और हर उस वैकल्पिक फ़ील्ड के लिए जिसका आपके पास वास्तविक उत्तर है। अंतिम-उपयोगकर्ता डेटा value के रूप में और हर दस्तावेज़ attachment_id के रूप में दें। किसी वैकल्पिक फ़ील्ड के लिए मान गढ़ने के बजाय उसे छोड़ दें। उदाहरण में दो उत्तर दिखाए गए हैं; भेजने से पहले बाकी आवश्यक उत्तर जोड़ें। यह अनुरोध उत्तरों को समीक्षा के लिए जमा करता है। प्रतिक्रिया से id, यानी सबमिशन का csb_ पहचानकर्ता, SUBMISSION_ID के रूप में रखें:

   कोड उदाहरण

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-CUST-778812" \
     --data '{"subject_kind": "number", "subject_id": "'"$NUMBER_ID"'", "program": "'"$PROGRAM"'", "country_code": "'"$COUNTRY_CODE"'", "answers": [{"key": "business_registration_number", "value": "90012768"}, {"key": "business_registration_certificate", "attachment_id": "'"$ATTACHMENT_ID"'"}]}'

   201 प्रतिक्रिया सबमिशन लौटाती है। 422 होने पर कुछ भी जमा नहीं होता: बॉडी ठीक करें और उसे नई idempotency कुंजी के साथ भेजें, क्योंकि पुरानी कुंजी अस्वीकृति को ही दोहराती है। हर उत्तर जमा करें में हर अस्वीकृति समझाई गई है।

5. जब कोई समीक्षक किसी उत्तर को अस्वीकार करता है, तो केवल वही उत्तर बदलें, जैसा अस्वीकृत उत्तर ठीक करें में बताया गया है:

   कोड उदाहरण

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-fix-1-CUST-778812" \
     --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}'

खरीदते समय ही कागज़ात जमा करने के लिए, वही answers POST /v1/numbers/orders के compliance ब्लॉक में भेजें। वह ऑर्डर मौजूदा numbers स्कोप का write स्तर पर उपयोग करता है, तब भी जब उसमें कागज़ात शामिल हों।

समीक्षा की प्रगति GET /v1/numbers/{number_id} पर ownership.status से देखें। उत्तर आपके व्यवसाय के नाम पर किया गया कानूनी कथन होते हैं, इसलिए केवल वही उत्तर जमा करें जिनकी पुष्टि उनके लिए ज़िम्मेदार किसी व्यक्ति ने की हो। किसी नंबर के स्वामित्व के कागज़ात जमा करें में हर अनुरोध, समीक्षा और ऑर्डर के साथ कागज़ात जमा करना समझाया गया है।

किसी नंबर को अपने SIP ट्रंक पर रूट करें

नए नंबर का अपना कोई रूट नहीं होता, इसलिए वह आपके वर्कस्पेस के डिफ़ॉल्ट रूट का पालन करता है। यह डिफ़ॉल्ट शुरुआत में reject होता है, लेकिन जिस वर्कस्पेस ने पहले से डिफ़ॉल्ट सेट किया है, वह नंबर आवंटित होते ही उसी के अनुसार नए नंबर की कॉल का उत्तर देता है। उसकी कॉल अपने उपकरण तक पहुँचाने के लिए इनबाउंड कॉलिंग चालू करके एक SIP ट्रंक बनाएँ, उसमें एक गेटवे जोड़ें और नंबर को उस ट्रंक की ओर सेट करें। SIP ट्रंक में बताया गया है कि अपने उपकरण को ट्रंक से कैसे जोड़ें।

1. इनबाउंड कॉलिंग चालू करके ट्रंक बनाएँ। प्रतिक्रिया से id, यानी ट्रंक का spt_ पहचानकर्ता, TRUNK_ID के रूप में रखें:

   कोड उदाहरण

   curl --request POST "$BIRD_API_URL/v1/voice/trunks" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: trunk-production-pbx" \
     --data '{"name": "Production PBX", "inbound_enabled": true}'

2. एक गेटवे जोड़ें। डिफ़ॉल्ट रूप से गेटवे को डायल किया गया और कॉल करने वाला नंबर E.164 में उनके + के साथ मिलता है। अगर आपका उपकरण + के बिना नंबर चाहता है, जैसा Telserv का {dnis} प्लेसहोल्डर देता था, तो डायल किए गए नंबर के लिए destination_format और कॉल करने वाले नंबर के लिए origination_format को {number} पर सेट करें:

   कोड उदाहरण

   curl --request POST "$BIRD_API_URL/v1/voice/trunks/$TRUNK_ID/gateways" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: gateway-pbx-primary" \
     --data '{"sip_uri": "sip:pbx.example.com:5060", "priority": 0, "destination_format": "{number}", "origination_format": "{number}"}'

   फ़ेलओवर के लिए दूसरा गेटवे जोड़ें; गेटवे को क्या चाहिए priority और नंबर फ़ॉर्मैट समझाता है। idempotency कुंजी के बिना वही गेटवे फिर से बनाने पर 409 और E21047 मिलता है।

3. नंबर का वॉइस रिकॉर्ड खोजें। नंबर के अंकों से खोजें और उस प्रविष्टि का id लें जिसका provider.number_id आवंटन का id है। इसे VOICE_NUMBER_ID के रूप में रखें:

   कोड उदाहरण

   curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \
     --header "Authorization: Bearer $BIRD_API_KEY"

4. नंबर को ट्रंक की ओर सेट करें:

   कोड उदाहरण

   curl --request PATCH "$BIRD_API_URL/v1/voice/numbers/$VOICE_NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"inbound_configuration": {"route": {"type": "trunk", "trunk_id": "'"$TRUNK_ID"'"}}}'

   200 प्रतिक्रिया नया रूट दिखाती है। जिस ट्रंक पर इनबाउंड कॉलिंग बंद है, वह 412 और E21052 लौटाता है।

किसी ट्रंक पर इनबाउंड कॉलिंग बंद करने या ट्रंक को हटाने पर उस पर रूट किया गया हर नंबर आपके वर्कस्पेस के डिफ़ॉल्ट रूट पर लौट जाता है, और इनबाउंड कॉलिंग फिर से चालू करने पर वे रूट बहाल नहीं होते। SIP ट्रंक पर कॉल पहुँचाएँ में यह व्यवहार और trunk, forward तथा reject रूट समझाए गए हैं।

अपने नंबरों का मिलान करें

सबसे बड़े पेज आकार के साथ पूरी सूची पढ़ें। अगला पेज पढ़ने के लिए हर पेज का next_cursor NEXT_CURSOR के रूप में भेजें, जब तक next_cursor का मान null न हो जाए। सूची कुल संख्या नहीं लौटाती।

curl "$BIRD_API_URL/v1/numbers?limit=100" \
  --header "Authorization: Bearer $BIRD_API_KEY"

curl "$BIRD_API_URL/v1/numbers?limit=100&starting_after=$NEXT_CURSOR" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Telserv के सूची फ़िल्टर Bird के फ़िल्टरों से इस तरह मेल खाते हैं:

अपनी सूची में नंबर ढूँढें में हर फ़िल्टर का विस्तार से विवरण है।

हर प्रविष्टि में pricing होता है, जिसमें प्रति recurring_period recurring_price और intervals_per_charge होते हैं। जब तक नंबर के लिए कोई कीमत तय न हो, recurring_price आपके संगठन की मौजूदा दर है, और हर नवीनीकरण पर उस समय लागू दर से शुल्क लिया जाता है, इसलिए पहले से लिया गया शुल्क इससे अलग हो सकता है। अपने सभी नंबरों की सूची देखें में बताया गया है कि हर नंबर का शुल्क किस मुद्रा में लिया जाता है, pricing या उसकी कीमतें कब null होती हैं, और pricing.error सेट होने पर क्या करें।

रिलीज़ किया गया नंबर इस सूची से हट जाता है, और number_id से उसे पढ़ने पर 404 मिलता है। अगर आपने उसे Bird में ऑर्डर किया था, तो उसका पूरा हुआ ऑर्डर GET /v1/numbers/orders में बना रहता है।

नंबर रिलीज़ करें

दोनों अनुरोध किसी समर्पित नंबर पर, उसके nda_ पहचानकर्ता से, लागू होते हैं; साझा नंबर को E14002 के साथ अस्वीकार किया जाता है। जिस अवधि का भुगतान आप कर चुके हैं, उसके अंत तक नंबर रखने के लिए उसे रद्द करें:

curl --request DELETE "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: cancel-CUST-778812"

202 प्रतिक्रिया नंबर को releases_at के साथ लौटाती है, जो उसकी भुगतान की गई अवधि का अंत है। तब तक नंबर की मौजूदा स्थिति बनी रहती है, उसकी सदस्यता नवीनीकृत नहीं होती, और उसी समय वह रिलीज़ हो जाता है। दोबारा अनुरोध करने पर वही releases_at मिलता है, और रद्दीकरण वापस नहीं लिया जा सकता। जिस नंबर के पीछे कोई सदस्यता नहीं है, वह तुरंत रिलीज़ हो जाता है, और प्रतिक्रिया 200 होती है, जिसमें नंबर का status released पर सेट होता है।

नंबर को अभी रिलीज़ करने के लिए, उस नंबर सहित जिसका रद्दीकरण पहले से निर्धारित है:

curl --request POST "$BIRD_API_URL/v1/numbers/$NUMBER_ID/release" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: release-CUST-778812"

204 प्रतिक्रिया का अर्थ है कि नंबर तुरंत प्रभाव से रिलीज़ हो गया है। मौजूदा अवधि के शेष हिस्से का पैसा वापस नहीं किया जाता।

जब तक नंबर के नवीनीकरण का भुगतान बकाया है, दोनों अनुरोध भुगतान होने तक E03015 के साथ 409 लौटाते हैं।

कोई भी अनुरोध तारीख नहीं लेता, इसलिए Telserv को भेजा गया शेड्यूल अपनी ओर requestedCancelDate के रूप में रखें। किसी नंबर को उसकी तारीख तक रखने के लिए, तारीख के उसकी मौजूदा बिलिंग अवधि में आते ही उसे रद्द करें: वह अवधि खत्म होने पर, यानी तारीख पर या उसके बाद, रिलीज़ हो जाता है। उसे ठीक उसी तारीख को छोड़ने के लिए, उसी दिन उसे रिलीज़ करें। नंबर रिलीज़ करें में बताया गया है कि हर अनुरोध नंबर, उसके शुल्कों और फिर से प्रयास पर क्या असर डालता है।

अपने नंबर पर टेस्ट कॉल करें

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

अनुरोध को test-call.json के रूप में सहेजें। from में वह कॉलर ID डालें जिसे आप दिखाते हैं, जो आपके वर्कस्पेस का स्वामित्व वाला या सत्यापित नंबर हो, और to में जाँचा जाने वाला नंबर डालें:

{
  "from": "+31612345679",
  "to": "+31612345678",
  "sequence": {
    "definition": {
      "schema_version": 1,
      "expression_environment": "bird.cel.v1",
      "nodes": [
        {
          "id": "entry",
          "type": "trigger.start_call",
          "type_version": 1,
          "config": {},
          "input": {},
          "connections": { "event": { "node_id": "end", "port": "input" } }
        },
        { "id": "end", "type": "voice.hangup", "type_version": 1, "config": {}, "input": {} }
      ]
    },
    "entry_node_id": "entry",
    "trigger_data": {}
  }
}

इसे भेजें:

curl --request POST "$BIRD_API_URL/v1/voice/calls" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${TEST_CALL_KEY:?Set TEST_CALL_KEY once for this test call}" \
  --data-binary @test-call.json

हर टेस्ट के लिए TEST_CALL_KEY को नया मान दें, और टाइमआउट या अस्पष्ट परिणाम के बाद उसी टेस्ट के लिए फिर से प्रयास करते समय उसे दोबारा इस्तेमाल करें: तीन घंटे के भीतर वही कुंजी और वही अनुरोध दूसरी कॉल करने के बजाय पहली स्वीकृति को दोहराते हैं। 202 प्रतिक्रिया कॉल को स्वीकार करती है और उसका initial_leg_id लौटाती है। स्वीकृति से यह साबित नहीं होता कि कॉल जुड़ी: GET /v1/voice/legs/{leg_id} से लेग पढ़ें, या GET /v1/voice/legs और उसके to फ़िल्टर से नंबर पर की गई लेग की सूची देखें, और जाँचें कि आपके उपकरण को कॉल मिली। वॉइस कॉल बनाएँ में कॉलर ID और गंतव्य की आवश्यकताएँ और फिर से प्रयास के नियम बताए गए हैं।

अगले कदम

• नंबर खरीदें और रिलीज़ करें
• अपने फ़ोन नंबर प्रबंधित करना
• किसी नंबर के स्वामित्व के कागज़ात जमा करें
• कॉल प्राप्त करना
• SIP ट्रंक
• आइडेम्पोटेंसी