API के ज़रिए SMS प्रेषक पंजीकृत करें

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

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

• एक API कुंजी, जिसमें प्रेषक और पंजीकरण बनाने के लिए राइट स्तर पर sms_management हो, और उनके कागज़ात जमा करने के लिए राइट स्तर पर compliance हो।
• पहले कीमतें और वॉलेट की धनराशि जाँचने के लिए, एक प्रत्यायोजित उपयोगकर्ता OAuth टोकन, जिसका विवरण पंजीकरण की कीमतें और वॉलेट की धनराशि जाँचें में है। API कुंजी संगठन की बिलिंग जानकारी नहीं पढ़ सकती।

उदाहरण आपकी कुंजी BIRD_API_KEY से, उसका क्षेत्रीय होस्ट BIRD_API_URL से, गंतव्य देश COUNTRY_CODE से, और पंजीकरण का scr_ पहचानकर्ता मिलने के बाद उसे REGISTRATION_ID से पढ़ते हैं।

पंजीकरण की कीमतें और वॉलेट की धनराशि जाँचें

डैशबोर्ड जैसी ही कीमत और वॉलेट जानकारी दिखाने के लिए GET /v1/organization/billing/prices/resolve और GET /v1/organization/billing/wallets का उपयोग करें। इन्हें पढ़ने के लिए org:billing:read वाला प्रत्यायोजित उपयोगकर्ता OAuth टोकन चाहिए। वर्कस्पेस API कुंजियाँ, संगठन मास्टर कुंजियाँ और सेवा-खाता टोकन संगठन बिलिंग की यह अनुमति नहीं दे सकते।

issuer, registration_endpoint, authorization_endpoint और token_endpoint पाने के लिए OAuth संरक्षित-संसाधन खोज और ऑथराइज़ेशन-सर्वर मेटाडेटा का उपयोग करें, जैसा OAuth खोज में बताया गया है। खोजे गए registration_endpoint पर अपना सार्वजनिक OAuth क्लाइंट पंजीकृत करें और client_name, redirect_uris और token_endpoint_auth_method: "none" दें। उपयोगकर्ता को खोजे गए authorization_endpoint पर भेजें, साथ में वही client_id, response_type=code, आपका पंजीकृत redirect_uri, एक नया state, scope=org:billing:read, आपके वेरिफ़ायर से बना code_challenge और code_challenge_method=S256 हों। सहमति स्क्रीन पर उपयोगकर्ता इच्छित संगठन का एक वर्कस्पेस चुनता है और जहाँ उसकी भूमिका अनुमति देती है वहाँ org:billing:read देता है। state को आपके भेजे गए मान से और iss को खोज से मिले जारीकर्ता से मिलाकर जाँचें, फिर खोजे गए token_endpoint पर कोड का विनिमय करें, साथ में grant_type=authorization_code, लौटाया गया code, client_id, वही redirect_uri और मूल code_verifier भेजें। मिले हुए एक्सेस टोकन का उपयोग BIRD_OAUTH_TOKEN के रूप में करें। उसके expires_in का पालन करें; रीफ़्रेश टोकन को सुरक्षित रूप से संग्रहीत करें और हर सफल रीफ़्रेश के बाद उसे बदलें। रीफ़्रेश के प्रयास एक-एक करके करें, क्योंकि हर रीफ़्रेश टोकन केवल एक बार उपयोग होता है। रीफ़्रेश ग्रांट की अवधि समाप्त होने या उसके रद्द होने पर दोबारा ऑथराइज़ करें।

टोकन चुने गए वर्कस्पेस और उसके संगठन से बंधा होता है; बिलिंग जानकारी उसी संगठन की पढ़ी जाती है। X-Organization-Id इसे किसी दूसरे संगठन पर नहीं बदल सकता; उस संगठन के लिए ऑथराइज़ेशन दोबारा करें। इस टोकन के साथ SDK कॉन्फ़िगर करते समय क्षेत्रीय होस्ट स्पष्ट रूप से सेट करें।

अल्फ़ान्यूमेरिक SMS सेंडर के लिए, गंतव्य देश के आधार पर उसके पंजीकरण का सेटअप मूल्य निकालें:

curl --get "$BIRD_API_URL/v1/organization/billing/prices/resolve" \
  --header "Authorization: Bearer $BIRD_OAUTH_TOKEN" \
  --data-urlencode 'product_slug=sms_sender_registration' \
  --data-urlencode "dimensions[country_code]=$COUNTRY_CODE" \
  --data-urlencode 'dimensions[sender_type]=alphanumeric'

curl "$BIRD_API_URL/v1/organization/billing/wallets" \
  --header "Authorization: Bearer $BIRD_OAUTH_TOKEN"

आवर्ती मूल्य के लिए उन्हीं आयामों के साथ product_slug=sms_sender निकालें। डैशबोर्ड जैसी ही बैलेंस जाँच के लिए, सेटअप प्रतिक्रिया के gross_price.amount को पहले आवर्ती शुल्क में जोड़ें, यानी आवर्ती प्रतिक्रिया के gross_price.amount को उसके intervals_per_charge से गुणा करके मिली राशि में। इस कुल राशि की तुलना data में मौजूद उस वॉलेट के balance से करें जिसका currency_code दोनों मूल्यों के gross_price.currency_code से मेल खाता है। लौटाई गई राशियों को राउंड किए बिना दशमलव गणना का उपयोग करें। अगर कुल राशि बैलेंस से अधिक है, तो अंतर ही कमी है; पंजीकरण बनाने से पहले वॉलेट में राशि जोड़ें या अपने संगठन की क्रेडिट व्यवस्था जाँचें। सर्वर अपनी अंतिम भुगतान-क्षमता जाँच में किसी भी क्रेडिट सीमा को भी ध्यान में रखता है। ये रीड मौजूदा मूल्य और राशि दिखाते हैं; ये न तो राशि आरक्षित करते हैं और न ही पंजीकरण को स्वीकृत करते हैं।

वह पंजीकरण प्राप्त करें जिसके लिए दस्तावेज़ जमा करने हैं

1. GET /v1/sms/senders या GET /v1/sms/senders/{sender_id} से सेंडर खोजें। ज़रूरत हो तो POST /v1/sms/senders से नया सेंडर बनाएँ।
2. गंतव्य के लिए GET /v1/sms/senders/{sender_id}/requirements पढ़ें। उसके next चरणों का पालन करें। अगर वह पंजीकरण बनाने को कहे, तो पंजीकरण मूल्य और वॉलेट राशि जाँचें में बताए अनुसार उसका मूल्य जाँचें, फिर country_code के साथ POST /v1/sms/senders/{sender_id}/registrations को कॉल करें।
3. सेंडर की आवश्यकताएँ फिर से पढ़ें और पंक्ति का registration_id (scr_) REGISTRATION_ID के रूप में और उसका program PROGRAM के रूप में रखें। दस्तावेज़ तभी जमा करें जब पंक्ति का has_compliance_requirements true हो; जब यह false हो, तो पंजीकरण को किसी सबमिशन की ज़रूरत नहीं है या कोई समर्पित प्रोग्राम उसे संभालता है, इसलिए उसके बजाय पंक्ति के next का पालन करें। टोल-फ़्री सत्यापन और 10DLC जैसे समर्पित प्रोग्रामों के अपने अलग चरण होते हैं।

सेंडर पढ़ने के लिए sms_management:read चाहिए; सेंडर और पंजीकरण बनाने के लिए sms_management:write चाहिए। उनके दस्तावेज़ जमा करने के लिए compliance:write भी चाहिए।

पंजीकरण के दस्तावेज़ जमा करें

यह अनुभाग उस पंजीकरण पर लागू होता है जिसका has_compliance_requirements true है।

sms_sender को subject_kind के रूप में और पंजीकरण को subject_id के रूप में देकर GET /v1/compliance/requirements से पढ़ें कि पंजीकरण क्या माँगता है:

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=sms_sender&subject_id=$REGISTRATION_ID&country_code=$COUNTRY_CODE&program=$PROGRAM" \
  --header "Authorization: Bearer $BIRD_API_KEY"

ये फ़ील्ड उसी तरह पढ़ी जाती हैं जैसे किसी नंबर के लिए; पढ़ें कि देश क्या माँगता है हर फ़ील्ड को समझाता है, और हर दस्तावेज़ अपलोड करें उन फ़ाइलों के बारे में बताता है जो document फ़ील्ड माँगती है। पंजीकरण को विषय के रूप में देकर हर उत्तर POST /v1/compliance/submissions से जमा करें:

curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: sender-$REGISTRATION_ID" \
  --data '{
    "subject_kind": "sms_sender",
    "subject_id": "'"$REGISTRATION_ID"'",
    "program": "'"$PROGRAM"'",
    "country_code": "'"$COUNTRY_CODE"'",
    "answers": [{ "key": "legal_entity_name", "value": "Goldcrest Communications Inc" }]
  }'

नमूने में एक उत्तर दिखाया गया है; हर उस फ़ील्ड के लिए एक प्रविष्टि भेजें जिसका required true है, और हर उस वैकल्पिक फ़ील्ड के लिए भी जिसका आपके पास वास्तविक उत्तर है, जैसा हर उत्तर जमा करें में बताया गया है। 201 प्रतिक्रिया सबमिशन लौटाती है; उसका csb_ id रखें। सेंडर में कोई ownership फ़ील्ड नहीं होती, इसलिए समीक्षा की प्रगति जानने के लिए GET /v1/compliance/submissions/{submission_id} से सबमिशन पढ़ें, जिसके उत्तरों में उनका state और अस्वीकार होने पर reason होता है, या पंजीकरण की स्थिति के लिए सेंडर की आवश्यकताएँ फिर से पढ़ें। अस्वीकार किए गए उत्तरों को POST /v1/compliance/submissions/{submission_id}/resupply से बदलें, जैसा अस्वीकार किया गया उत्तर सुधारें में दिखाया गया है।

अगले कदम

• किसी नंबर के स्वामित्व के कागज़ात जमा करें
• SMS सेंडर आईडी