eSIM API को इंटीग्रेट करें

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

ऑफ़र और संसाधन देखने के लिए कुंजी को esim:read दें, और सेवा खरीदने या प्रबंधित करने के लिए esim:write दें। इंस्टॉलेशन क्रेडेंशियल की अनुमतियाँ अलग हैं: उन्हें प्राप्त करने के लिए esim_credentials:read और इंस्टॉलेशन लिंक बनाने या भेजने के लिए esim_credentials:write। API कुंजी को अपने सर्वर एप्लिकेशन में ही रखें।

1. ऑफ़र चुनें

गंतव्य के लिए ऑफ़र की सूची देखें, फिर चुना गया ऑफ़र प्राप्त करें। zone.countries, pricing में दी गई डेटा सीमा और वैधता, स्पीड की शर्तें और शामिल फ़ोन सेवा, यदि कोई हो, जाँचें। मौजूदा eSIM के लिए संगत ऑफ़र की सूची देखें; कैटलॉग में किसी ऑफ़र के उपलब्ध होने से यह तय नहीं होता कि वह टॉप-अप के लिए संगत है।

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

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

नीचे दिए गए एकबारगी उदाहरण के लिए curl और jq इंस्टॉल करें। BIRD_API_URL को अपने क्षेत्रीय बेस URL पर, BIRD_API_KEY को अपनी कुंजी पर और ESIM_OFFER_ID को चुने गए ऑफ़र ID पर सेट करें:

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/offers/$ESIM_OFFER_ID/checkout" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  > esim-checkout.json

jq '.one_time' esim-checkout.json

आगे बढ़ने से पहले कीमत और ऑफ़र की शर्तों की समीक्षा करें। कोटेशन से उपलब्धता आरक्षित नहीं होती।

2. खरीदारी बनाएँ

offer_id के साथ ऑर्डर बनाएँ। नई प्रोफ़ाइल के लिए esim_id छोड़ दें, टॉप-अप के लिए इसे शामिल करें। एक बार की खरीद के लिए स्वीकार किए गए कोट से offer_revision और expected_price भेजें। शर्तें बदल गई हों तो ये फ़ील्ड शुल्क लगने से पहले ही 409 के साथ अनुरोध अस्वीकार कर देते हैं। बदली हुई कीमत स्वीकार करने से पहले नया कोट प्राप्त करें और उसकी समीक्षा करें।

इस खरीद के लिए ESIM_ORDER_KEY को एक अद्वितीय मान पर सेट करें और उसे अनुरोध के साथ सहेजें। यह उदाहरण एक नया, असाइन न किया गया eSIM खरीदता है और प्रकाशित कीमत को उसकी राशि या मुद्रा बदले बिना कॉपी करता है:

jq '{offer_id, offer_revision: .one_time.offer_revision, expected_price: .one_time.price}' \
  esim-checkout.json > esim-order.json

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/orders" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ESIM_ORDER_KEY" \
  --data-binary @esim-order.json

डिलीवरी पूरी होने पर नई प्रोफ़ाइल असाइन करने के लिए वर्कस्पेस का subscriber_id शामिल करें और सब्सक्राइबर सेटअप का पालन करें। टॉप-अप में मौजूदा असाइनमेंट बना रहता है, इसलिए esim_id भेजते समय subscriber_id छोड़ दें। इंस्टॉलेशन विवरण डिलीवरी के बाद अलग से भेजें।

लौटाया गया ऑर्डर ID सहेजें। HTTP 201 के बाद भी status जाँचें, क्योंकि इसमें पूरा हुआ या विफल ऑर्डर हो सकता है। HTTP 202 का अर्थ है कि प्रोसेसिंग जारी है। ऑर्डर के completed या failed होने तक ऑर्डर प्राप्त करें। पूरा हुआ ऑर्डर esim_id और package_id बताता है। डिवाइस पर इंस्टॉलेशन एक अलग चरण है।

3. इंस्टॉलेशन विवरण दें

खरीद के बाद इंस्टॉलेशन क्रेडेंशियल पढ़ें, होस्ट किया गया इंस्टॉलेशन लिंक बनाएँ, या ईमेल या SMS से लिंक भेजें। एक्टिवेशन विवरण और इंस्टॉलेशन लिंक को एनालिटिक्स और सार्वजनिक लॉग से बाहर रखें।

भेजे गए लिंक के लिए डिलीवरी ID सहेजें और डिलीवरी इतिहास देखें। 202 प्रतिक्रिया पुष्टि करती है कि लिंक भेजने के लिए स्वीकार हो गया है। delivered संदेश की डिलीवरी की पुष्टि करता है, और डिवाइस पर इंस्टॉलेशन की अलग से जाँच करनी होती है। समर्थित तरीकों, लिंक की समाप्ति और रिकवरी के लिए इंस्टॉलेशन गाइड का पालन करें।

4. बाधित खरीद को रिकवर करें

यदि create प्रतिक्रिया खो गई या उसने 503 लौटाया, तो सहेजे गए अनुरोध को उसकी मूल Idempotency-Key के साथ दोहराएँ। idempotent अनुरोध देखें। यदि आपके पास ऑर्डर ID है, तो पहले वह ऑर्डर पढ़ें। परिणाम अनिश्चित रहते हुए दूसरी खरीद बनाने से दोबारा शुल्क लग सकता है।

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

funding.lapses_at के बाद भी ऑर्डर की मौजूदा स्थिति जाँचें, क्योंकि यह टाइमस्टैम्प रद्द होने की गारंटी नहीं देता। यदि अपर्याप्त फ़ंड का अगला प्रयास ऑर्डर को विफल करने से पहले उसे फ़ंड मिल जाए, तो ऑर्डर फिर भी पूरा हो सकता है।

अनचाही, बिना फ़ंड वाली खरीद रोकने के लिए ऑर्डर रद्द करें। बिना फ़ंड वाला ऑर्डर सफलतापूर्वक रद्द होने पर status: failed और failure_code: canceled लौटते हैं। फ़ंड वाला एक बार का ऑर्डर 409 लौटाता है और जारी रहता है। शुरुआती रिकरिंग खरीद में, रद्द करने के दौरान भुगतान रिकवर हो जाने पर भुगतान की गई खरीद जारी रह सकती है, जबकि आगे का रिन्यूअल रुक जाता है। रद्द होने या रिफ़ंड की सूचना देने से पहले लौटाए गए ऑर्डर और सब्सक्रिप्शन की जाँच करें।

विफल खरीदारी के लिए failure_code और failure_reason जाँचें। लिया गया कोई भी शुल्क अपने-आप क्रेडिट हो जाता है; refund_transaction_id जारी किए गए क्रेडिट की पहचान बताता है। अगर भुगतान, डिलीवरी या क्रेडिट का मामला अनसुलझा रहे, तो सहायता के लिए ऑर्डर ID सँभालकर रखें।

5. बैलेंस और सेवा की स्थिति दिखाएँ

स्थिति, इंस्टॉलेशन की स्थिति, पैकेज और available_actions के लिए eSIM प्राप्त करें। उपयोग गाइड की मदद से पैकेज का अलाउंस, खपत और अवलोकन का समय दिखाएँ। अगर खपत अज्ञात है, तो आपके ऐप्लिकेशन में भी उसे अज्ञात ही दिखाना चाहिए।

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

अगले चरण

• यात्रा पैकेज चुनें।
• डिवाइस इंस्टॉलेशन की तैयारी करें।
• आवर्ती पैकेज प्रबंधित करें।