किसी नंबर के स्वामित्व के कागज़ात दाखिल करें

कुछ देश यह जानना चाहते हैं कि नंबर किसके पास है, उसके बाद ही नंबर पर ट्रैफ़िक चल सकता है। जब तक वे कागज़ात स्वीकार नहीं होते और नंबर का पंजीकरण पूरा नहीं होता, तब तक नंबर आपको आवंटित रहता है और उसका बिल बनता है, लेकिन उसका status pending_ownership_registration होता है: उस पर न आने वाली और न जाने वाली वॉइस कॉल चलती हैं और न ही वह SMS भेजता है। जब नंबर का status active और उसका ownership.blocked_at null हो जाता है, तब नंबर पर ट्रैफ़िक चलने लगता है। आप कागज़ात डैशबोर्ड से या API से दाखिल करते हैं, और दोनों तरीकों में वही आवश्यकताएँ, समीक्षा के नियम और पंजीकरण प्रक्रिया लागू होती हैं। नंबर का ownership.next हर चरण बताता है, जिसमें यह भी शामिल है कि नया सबमिशन कब दाखिल करना है।

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

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

• डैशबोर्ड से दाखिल करने के लिए, आपकी वर्कस्पेस भूमिका में अनुपालन विवरण संपादित करने की अनुमति होनी चाहिए। इसके बिना, नंबर अपनी स्वामित्व स्थिति तो दिखाता है, लेकिन दाखिल करने का बटन नहीं दिखाता।
• अलग अनुपालन एंडपॉइंट के ज़रिए दाखिल करने के लिए, लिखने के स्तर पर compliance स्कोप वाली API कुंजी चाहिए। पढ़ने के स्तर वाली कुंजी आवश्यकताएँ और समीक्षा की प्रगति जाँच सकती है, लेकिन दाखिल नहीं कर सकती। नंबर पढ़ने के लिए पढ़ने के स्तर पर numbers स्कोप भी चाहिए। डैशबोर्ड के कुंजी चयनकर्ता में, compliance Compliance के अंतर्गत है।
• नंबर का nda_ पहचानकर्ता, जो GET /v1/numbers से मिलता है। अपनी सूची में नंबर खोजें बताता है कि इसे कैसे खोजें।

API उदाहरण आपकी कुंजी BIRD_API_KEY से, उसका क्षेत्रीय होस्ट BIRD_API_URL से, और नंबर का पहचानकर्ता NUMBER_ID से पढ़ते हैं। आगे का हर चरण वह वेरिएबल बताता है जिसे वह सेट करता है। jq कमांड प्रतिक्रिया से एक फ़ील्ड निकालते हैं; अगर आप jq का उपयोग नहीं करते, तो फ़ील्ड को खुद पढ़ें।

जाँचें कि नंबर के लिए कागज़ात चाहिए या नहीं

GET /v1/numbers/{number_id} से नंबर पढ़ें:

curl "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY"

नंबर के country_code को COUNTRY_CODE के रूप में सहेजें; आवश्यकताएँ पढ़ने के अनुरोध और सबमिशन, दोनों में इसकी ज़रूरत होती है:

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

जब नंबर का देश कोई कागज़ात नहीं माँगता, तो ownership का मान null होता है। यह तब भी null होता है जब हम कागज़ात की प्रगति नहीं पढ़ पाए और नंबर पर कोई रोक दर्ज नहीं है; ऐसे में नंबर को फिर से पढ़ें। अन्यथा इसमें ये होते हैं:

• status: needs_input का अर्थ है कि उत्तर अधूरे हैं या उनमें सुधार ज़रूरी है, under_review का अर्थ है कि आपके उत्तरों की समीक्षा हो रही है, approval_pending का अर्थ है कि कागज़ात स्वीकार हो गए हैं और पंजीकरण अभी लंबित है; जब तक blocked_at सेट है, कॉल और भेजे जाने वाले SMS रुके रहते हैं। approved का अर्थ है कि पंजीकरण स्वीकृत हो गया है, फिर भी जब तक blocked_at सेट है, कॉल और भेजे जाने वाले SMS रुके रहते हैं। not_required का अर्थ है कि और कुछ नहीं माँगा गया है। rejected का अर्थ है कि सबमिशन बंद कर दिया गया या सुधार की समय-सीमा बीत गई, और अब इसमें कोई सुधार स्वीकार नहीं होता। इसे फिर से खुलवाने के लिए सहायता टीम से संपर्क करें। unknown का अर्थ है कि स्थिति पढ़ी नहीं जा सकी; नंबर को फिर से पढ़ें।
• next: कागज़ात की प्रक्रिया आगे बढ़ाने वाले चरण, क्रम से। wait चरण का अर्थ है कि अभी आपसे कुछ नहीं माँगा गया है। हर बदलाव के बाद इसे फिर से पढ़ें।
• submission_id: नंबर का सबसे हाल का सबमिशन, जब कोई सबमिशन मौजूद हो।
• blocked_at: स्वामित्व से जुड़ी रोक कब शुरू हुई, या रोक हटने के बाद null। यह रोक आने और जाने वाली वॉइस कॉल और भेजे जाने वाले SMS को रोकती है।

आवंटित नंबर की स्थिति बताता है कि ownership का नंबर के अपने status से क्या संबंध है।

डैशबोर्ड से जमा करें

1. Numbers पेज से नंबर खोलें। इसकी Ownership पंक्ति में कागज़ात की स्थिति और अगले चरण दिखते हैं।
2. जब स्थिति Details needed हो, तो Update ownership details चुनें। Prove ownership of this number फ़ॉर्म खुलता है।
3. वह व्यवसाय चुनें जिसके पास नंबर है, या नए व्यवसाय का विवरण दें, फिर हर मद का उत्तर दें और उसके माँगे गए दस्तावेज़ अपलोड करें। जिन मदों के साथ खाली फ़ॉर्म दिया गया है, उनमें उसका लिंक होता है, ताकि आप उसे डाउनलोड करके भरें और वापस अपलोड करें।
4. Submit answers चुनें।

Ownership पंक्ति Under review पर चली जाती है। अगर कोई समीक्षक किसी उत्तर को अस्वीकार करता है, तो पंक्ति फिर से Details needed पर लौट आती है। तब Update ownership details को दोबारा चुनें, फ़ॉर्म में दिखाए गए उत्तर सुधारें, और उन्हें भेजने के लिए फ़ॉर्म के अंत में Update ownership details चुनें।

अगर नंबर के देश के लिए अभी कोई फ़ॉर्म नहीं है, तो फ़ॉर्म पेज पर Ownership form unavailable दिखता है। उस देश के लिए अनुरोध करने हेतु सहायता टीम से संपर्क करें।

API से दाखिल करें

API से दाखिल करने के लिए, पहले पढ़ें कि देश क्या माँगता है, फिर हर दस्तावेज़ अपलोड करें, सभी उत्तर एक साथ सबमिट करें, और समीक्षा की प्रगति देखने के लिए नंबर को पढ़ें।

पढ़ें कि देश क्या माँगता है

GET /v1/compliance/requirements से नंबर की आवश्यकताएँ पढ़ें। subject_kind को number पर, subject_id को नंबर के nda_ पहचानकर्ता पर, और country_code को नंबर के अपने COUNTRY_CODE पर सेट करें:

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

प्रतिक्रिया उस program का नाम बताती है जिसके अंतर्गत नंबर पंजीकृत होता है; यह नंबर के प्रकार पर निर्भर करता है। इसे PROGRAM के रूप में रखें। प्रतिक्रिया fields में उत्तर देने योग्य हर आइटम उसी क्रम में सूचीबद्ध करती है जिसमें उन्हें दिखाना है। हर फ़ील्ड के लिए:

• key वह नाम है जिसके अंतर्गत आप उत्तर भेजते हैं।
• data_type बताता है कि उत्तर कैसे देना है। document फ़ील्ड में अपलोड की गई फ़ाइल दी जाती है; बाकी हर प्रकार में स्ट्रिंग दी जाती है, इसलिए संख्या "1500" के रूप में और हाँ-या-नहीं "true" के रूप में जाता है। enum फ़ील्ड अपने options में से एक मान स्वीकार करता है।
• required बताता है कि स्वीकृति इस उत्तर पर निर्भर है या नहीं, और help_text बताता है कि सही उत्तर कैसा होता है।
• max_items उस फ़ील्ड पर सेट होता है जिसमें एक से अधिक उत्तर दिए जा सकते हैं।
• जिस फ़ील्ड के लिए खाली फ़ॉर्म उपलब्ध है, उसमें template_url उस फ़ॉर्म का लिंक देता है, जिसे आप डाउनलोड करके, भरकर, वापस अपलोड करते हैं।
• state बताता है कि आइटम किस स्थिति में है: उत्तर देने से पहले not_supplied, फिर supplied, in_review, approved या rejected, और अस्वीकृत आइटम पर समीक्षक का reason होता है। स्वीकृत उत्तर बाद में expired दिखा सकता है, तब उसे फिर से देना होता है, और not_applicable ऐसे आइटम को चिह्नित करता है जो आप पर लागू नहीं होता।

जब तक आप फ़ाइल नहीं करते, submission_id का मान null रहता है। जब तक कोई भी आइटम आपकी प्रतीक्षा में है, needs_input का मान true रहता है।

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

हर दस्तावेज़ अपलोड करें

document फ़ील्ड जो भी फ़ाइल माँगता है, उसे POST /v1/compliance/attachments से multipart/form-data बॉडी के रूप में अपलोड करें, जिसमें बाइट file भाग में हों। प्रतिक्रिया से id, यानी अटैचमेंट का tca_ पहचानकर्ता, ATTACHMENT_ID के रूप में रखें:

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

10 MB तक की PNG, JPEG और PDF फ़ाइलें स्वीकार की जाती हैं, और प्रकार फ़ाइल की सामग्री से पढ़ा जाता है। 201 प्रतिक्रिया नया अटैचमेंट लौटाती है। वही फ़ाइल दोबारा अपलोड करने पर पहला अटैचमेंट 200 के साथ लौटता है, इसलिए अपलोड का फिर से प्रयास करने से डुप्लिकेट नहीं बनता। जिस अटैचमेंट का किसी सबमिशन में उल्लेख नहीं है, वह सात दिन बाद समाप्त हो जाता है।

अटैचमेंट का download_url एक हस्ताक्षरित लिंक है, जो अटैचमेंट प्राप्त करने के समय से 24 घंटे तक मान्य रहता है। नया लिंक पाने के लिए GET /v1/compliance/attachments से अपने अटैचमेंट की सूची देखें, या GET /v1/compliance/attachments/{attachment_id} से बाइट सीधे डाउनलोड करें।

सभी उत्तर सबमिट करें

POST /v1/compliance/submissions से उत्तर फ़ाइल करें। subject_kind और subject_id, आवश्यकताएँ पढ़ने पर मिला program, और नंबर का country_code भेजें। answers में हर उस फ़ील्ड के लिए एक प्रविष्टि भेजें जिसका required true है, और हर उस वैकल्पिक फ़ील्ड के लिए एक प्रविष्टि भेजें जिसका आपके पास वास्तविक उत्तर है। किसी वैकल्पिक फ़ील्ड के लिए मान गढ़ने के बजाय उसे छोड़ दें। टाइप वाला फ़ील्ड value लेता है, दस्तावेज़ फ़ील्ड attachment_id लेता है, और max_items वाला फ़ील्ड values या attachment_ids लेता है। <NUMBER_ID>, <PROGRAM>, <COUNTRY_CODE> और <ATTACHMENT_ID> की जगह अपने मान डालकर बॉडी को submission.json के रूप में सहेजें। उदाहरण में फ़ॉर्म द्वारा माँगे गए उत्तरों में से तीन दिखाए गए हैं:

{
  "subject_kind": "number",
  "subject_id": "<NUMBER_ID>",
  "program": "<PROGRAM>",
  "country_code": "<COUNTRY_CODE>",
  "answers": [
    { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" },
    { "key": "business_registration_number", "value": "90012768" },
    { "key": "business_registration_certificate", "attachment_id": "<ATTACHMENT_ID>" }
  ]
}

इसे Idempotency-Key के साथ भेजें। कुंजी का दोबारा उपयोग केवल उसी बॉडी का फिर से प्रयास करने के लिए करें, क्योंकि अस्वीकृति भी सहेजी और दोहराई जा सकती है। इसलिए 422 मिलने के बाद बॉडी ठीक करें और उसे नई कुंजी के साथ भेजें। आइडेम्पोटेंसी बताता है कि क्या सहेजा जाता है।

curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ownership-$NUMBER_ID" \
  --data-binary @submission.json

कोई ड्राफ़्ट नहीं होता: यह अनुरोध उत्तरों को समीक्षा के लिए फ़ाइल करता है, इसलिए इसमें हर आवश्यक उत्तर होना चाहिए। यदि आप कोई आवश्यक फ़ील्ड छोड़ देते हैं या फ़ॉर्म कोई उत्तर अस्वीकार करता है, तो E01001 वाला 422 लौटता है। उसके details में हर फ़ील्ड के लिए एक प्रविष्टि होती है, जिसका नाम param में होता है, और कुछ भी फ़ाइल नहीं होता। 201 प्रतिक्रिया सभी उत्तरों सहित सबमिशन लौटाती है। उसका id, यानी सबमिशन का csb_ पहचानकर्ता, SUBMISSION_ID के रूप में रखें।

आपका वर्कस्पेस जिस व्यवसाय का विवरण देता है, वह एक पहचान है। डैशबोर्ड के Identity Center में या POST /v1/compliance/identities से उसका प्रदर्शन name भेजकर पहचान बनाएँ। नंबर सबमिशन में identity_id की जगह इनलाइन identity भी भेजा जा सकता है। सबमिशन प्रतिक्रिया का identity_id नई पहचान बताता है, जिसे POST /v1/compliance/identities id के रूप में लौटाता है। बाद के नंबरों के लिए नई पहचान बनाने के बजाय इसी का दोबारा उपयोग करें। किसी पहचान के लिए फ़ाइल करने हेतु उसका identity_id जोड़ें, और जो उत्तर आप छोड़ते हैं वे उस पहचान में सहेजे गए उत्तरों से भर जाते हैं। GET /v1/compliance/identities व्यवसाय की पहचानों की सूची देता है। आपके द्वारा फ़ाइल किए गए एकल-मान उत्तर समीक्षा के निर्णय से स्वतंत्र रूप से पहचान पर वापस लिखे जाते हैं, इसलिए उस पहचान वाला अगला सबमिशन उन्हीं से शुरू होता है। दस्तावेज़ और बहु-मान उत्तर हर बार फिर से माँगे जाते हैं। हर व्यवसाय के लिए एक पहचान रखें: यदि आप कई अंतिम ग्राहकों के लिए फ़ाइल करते हैं, तो हर ग्राहक को उसकी अपनी पहचान दें, वरना एक ग्राहक के स्वीकृत उत्तर दूसरे के उत्तरों में भर जाएँगे।

दोबारा फ़ाइल करने के बजाय ownership.next का पालन करें। किसी नंबर के देश के फ़ॉर्म के हर संस्करण के लिए उस नंबर का एक ही सबमिशन होता है, इसलिए वह सबमिशन खुला रहते हुए दोबारा फ़ाइल करने पर E19009 के साथ 409 लौटता है: इसके बजाय उसे सुधारें, जैसा अस्वीकृत उत्तर सुधारें में बताया गया है। जब फ़ॉर्म बदलने के बाद हम किसी बंद सबमिशन को फिर से खोलते हैं, तो next एक नया सबमिशन POST /v1/compliance/submissions पर भेजने के लिए कहता है।

समीक्षा की प्रगति देखें

हर उत्तर की समीक्षा अलग से होती है। नंबर को फिर से पढ़ें और ownership.status तथा ownership.next जाँचें, जैसा जाँचें कि नंबर को कागज़ात चाहिए या नहीं में बताया गया है। हर उत्तर का निर्णय देखने के लिए GET /v1/compliance/submissions/{submission_id} से सबमिशन पढ़ें, या आवश्यकताएँ फिर से पढ़ें: हर फ़ील्ड में उसका state होता है और अस्वीकृत होने पर उसका reason भी।

समीक्षा पूरी होने पर हम परिणाम आपके संगठन के मालिकों को ईमेल करते हैं, और उस अंतिम दर्ज व्यक्ति को भी जिसने सबमिशन फ़ाइल किया या सुधारा, यदि ऐसा कोई व्यक्ति दर्ज है। API कुंजी से की गई पहली फ़ाइलिंग का परिणाम मालिकों को जाता है। बाद में API कुंजी से किए गए सुधार में पहले दर्ज व्यक्ति प्राप्तकर्ता बना रहता है। आपका इंटीग्रेशन ownership.status पढ़कर परिणाम जानता है।

अस्वीकृत उत्तर सुधारें

बदले हुए उत्तर POST /v1/compliance/submissions/{submission_id}/resupply पर भेजें। केवल वे उत्तर शामिल करें जिन्हें आप बदल रहे हैं; बाकी उत्तर जैसे हैं वैसे ही रहते हैं। submission_id नंबर के ownership से या आवश्यकताएँ पढ़ने के परिणाम से लें:

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-$NUMBER_ID" \
  --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}'

200 प्रतिक्रिया आपके बदले हुए उत्तरों के साथ सबमिशन लौटाती है, और वे उत्तर फिर से समीक्षा में जाते हैं। जब कोई भी आवश्यक उत्तर अस्वीकृत, समाप्त या अनुपस्थित नहीं रहता, तो नंबर का ownership.status वापस under_review हो जाता है। उन उत्तरों को बदलें जिनका state rejected, expired या not_supplied है। जब हम आपके उत्तर स्वीकार करने के बाद सुधार माँगते हैं, तो जिस उत्तर का editable_for_verifier_repair true है, उसे भी उस सुधार के बंद होने तक बदला जा सकता है। किसी अन्य स्थिति वाला उत्तर, जैसे जो अभी समीक्षा में है या हमारे माँगे गए सुधार के बाहर स्वीकृत हुआ है, बदलने पर E19003 के साथ 422 लौटता है। बदला गया दस्तावेज़ एक नया अपलोड है: पहले उसे अपलोड करें और फिर उसका attachment_id भेजें।

ऑर्डर के साथ कागज़ात फ़ाइल करें

यदि नंबर खरीदते समय आपको उत्तर पता हैं, तो उन्हें POST /v1/numbers/orders पर ऑर्डर के compliance ब्लॉक में भेजें, उसी answers ढाँचे में जो सबमिशन लेता है। नंबर आपके पास आने से पहले यह जानने के लिए कि देश क्या माँगता है, आवश्यकताएँ पढ़ने का अनुरोध subject_id के बिना करें, और COUNTRY_CODE तथा NUMBER_TYPE को GET /v1/numbers/available में नंबर के country_code और number_type पर सेट करें:

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

compliance ब्लॉक वाला ऑर्डर ऑर्डर के मौजूदा numbers स्कोप का राइट स्तर उपयोग करता है।

ऑर्डर स्वीकार होने के बाद वह हर स्थिति में पूरा होता है: यदि compliance ब्लॉक की फ़ाइलिंग अस्वीकार हो जाती है, तब भी नंबर आपका रहता है, और आप हर उत्तर सबमिट करें की तरह POST /v1/compliance/submissions से फ़ाइल करते हैं। उत्तर फ़ाइल होने पर नया नंबर अपने submission_id के साथ under_review दिखाता है। ऑर्डर के बारे में नंबर खरीदें और छोड़ें में बताया गया है।

व्यवसाय की पहचान का दोबारा उपयोग करें

व्यवसाय और उसके सहेजे गए उत्तर पढ़ने के लिए GET /v1/compliance/identities/{identity_id} का उपयोग करें। सहेजे गए उत्तरों में समीक्षा का state, reason और decided_at शामिल हो सकते हैं; जिस मान पर समीक्षा का कोई निर्णय नहीं हुआ है, उसमें स्थिति न भी हो सकती है। व्यवसाय का नाम PATCH /v1/compliance/identities/{identity_id} से बदलें, या उसे DELETE /v1/compliance/identities/{identity_id} से हटाएँ। पढ़ने के लिए compliance:read चाहिए; बनाने, नाम बदलने और हटाने के लिए compliance:write चाहिए।

व्यवसाय का स्वयं सत्यापन करने के लिए पहले पहचान बनाएँ। आवश्यकताएँ subject_kind=identity, उसके cid_ पहचानकर्ता को subject_id के रूप में, program=business और country_code=ZZ के साथ पढ़ें। उसी पहचान के लिए कागज़ात दाखिल करें। किसी नंबर के सबमिशन में इनलाइन पहचान इस पहचान-सत्यापन प्रक्रिया की जगह नहीं लेती।

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

इसके बजाय SMS प्रेषक के लिए दाखिल करें

SMS प्रेषक के कागज़ात में वही आवश्यकताएँ, अटैचमेंट, सबमिशन और सुधार अनुरोध उपयोग होते हैं, और विषय प्रेषक का पंजीकरण होता है। वह पंजीकरण पाने और पहले उसकी कीमत जाँचने का तरीका API से SMS प्रेषक पंजीकृत करें में बताया गया है।

जब कोई अनुरोध अस्वीकार हो जाए

त्रुटियाँ पेज त्रुटि प्रतिक्रिया का बॉडी और उसका remediation समझाता है।

अगले कदम

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