Vio eSIM
REST API · v1

Vio eSIM API संदर्भ

एक ही बैकएंड पर दो REST सतहें: ग्राहक-सामना करने वाला API जो वेब ऐप और हमारे iOS/Android ऐप को शक्ति देता है, और Vio eSIM को प्रोग्रामेटिक रूप से पुनर्विक्रय करने के लिए एक अलग, API-कुंजी-प्रमाणीकृत पार्टनर API।

मोबाइल / वेब API
https://vioesim.com/api/v1
पार्टनर API
https://vioesim.com/api/public/v1

मोबाइल ऐप प्रमाणीकरण

वेब ऐप और नेटिव ऐप एक ही सेशन सिस्टम साझा करते हैं — नेटिव ऐप केवल कुकी स्टोर पर निर्भर होने के बजाय टोकन स्वयं रखता है।

रजिस्टर या लॉगिन करें। दोनों एंडपॉइंट यूज़र ऑब्जेक्ट के साथ एक token फ़ील्ड लौटाते हैं (साथ ही Set-Cookie हेडर जिसका उपयोग वेब ऐप इसके बजाय करता है)। token को Keychain (iOS) या Keystore-समर्थित स्टोर (Android) में सहेजें।

हर अनुरोध पर इसे वापस भेजें:

Authorization: Bearer <token>

टोकन वैधता: जारी होने से 30 दिन, या जब तक /api/v1/auth/logout कॉल न हो। कोई रिफ्रेश-टोकन चरण नहीं है — जल्द समाप्त होने वाले टोकन को उपयोगकर्ता को फिर से लॉगिन करवाकर बस बदल दिया जाता है।

निलंबित, प्रतिबंधित या हटाए गए खातों के सेशन तुरंत काम करना बंद कर देते हैं, भले ही टोकन स्वयं समाप्त न हुआ हो — यह हर अनुरोध पर सर्वर-साइड जाँचा जाता है।

पार्टनर API प्रमाणीकरण

उन बाहरी व्यवसायों के लिए जो अपनी वेबसाइट या ऐप के माध्यम से Vio eSIM का पुनर्विक्रय करते हैं। एक पार्टनर एक सामान्य Vio eSIM खाता होता है: यहाँ से एक कुंजी जनरेट करें डैशबोर्ड → API कुंजियाँ (केवल एक बार दिखाई जाती है — इसे सहेज लें, इसे दोबारा नहीं देखा जा सकता), फिर इसे हर अनुरोध पर भेजें:

Authorization: Bearer vio_live_sk_...
# or
X-API-Key: vio_live_sk_...

एक नई कुंजी जनरेट करने से पिछली कुंजी तुरंत अमान्य हो जाती है।

बिलिंग मॉडल: पार्टनर API ऑर्डर खाते के प्रीपेड वॉलेट बैलेंस से समकालिक रूप से डेबिट किए जाते हैं — चूंकि यह एक सर्वर-टू-सर्वर कॉल है, इसलिए कोई चेकआउट रीडायरेक्ट नहीं है। ऑर्डर देने से पहले डैशबोर्ड (कार्ड/क्रिप्टो) से फंड जोड़ें। अपर्याप्त बैलेंस पर, POST /orders 402 लौटाता है।

क्विकस्टार्ट — पार्टनर API

कैटलॉग ब्राउज़ करें और दो कॉल में eSIM खरीदें:

curl https://vioesim.com/api/public/v1/destinations \
  -H "Authorization: Bearer vio_live_sk_..."

curl -X POST https://vioesim.com/api/public/v1/orders \
  -H "Authorization: Bearer vio_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "planId": "cus...", "quantity": 1 }'

त्रुटियाँ और दर सीमाएँ

मोबाइल/वेब API { "error": "संदेश" } लौटाता है (वर्तमान में तुर्की संदेश)। पार्टनर API एक संरचित प्रारूप लौटाता है ताकि आप code पर शाखा बना सकें:

{ "error": { "code": "INSUFFICIENT_BALANCE", "message": "Insufficient wallet balance." } }
स्थितिअर्थ
401टोकन या API कुंजी गुम, अमान्य या समाप्त
402केवल पार्टनर API — वॉलेट बैलेंस अपर्याप्त
404संसाधन नहीं मिला, या कॉलर के स्वामित्व में नहीं
409स्थिति संघर्ष (जैसे गैर-शून्य बैलेंस वाले खाते को हटाना)
429दर सीमा तक पहुँचे — Retry-After हेडर (सेकंड में) देखें
502शुल्क लिया गया लेकिन eSIM प्रावधान विफल — फिर से शुल्क न लें

दर सीमाएँ (पार्टनर API): रीड 120 प्रति मिनट प्रति कुंजी, POST /orders 30 प्रति मिनट।

मोबाइल / वेब API

प्रमाणीकरण

POST/api/v1/auth/registerप्रमाणीकरण आवश्यक नहीं

रजिस्टर

एक खाता और सक्रिय सेशन बनाता है।

Request body
{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "email": "[email protected]",
  "password": "min 8 chars"
}
200 OK
{
  "success": true,
  "user": {
    "id", "firstName", "lastName", "fullName", "email",
    "emailVerified", "walletBalance", "currency", "locale", "createdAt"
  },
  "token": "..."
}
POST/api/v1/auth/loginप्रमाणीकरण आवश्यक नहीं

लॉगिन

बॉडी: { email, password }। रजिस्टर के समान प्रतिक्रिया प्रारूप। गलत क्रेडेंशियल पर 401, निलंबित खाते पर 403।

POST/api/v1/auth/logoutसेशन टोकन

लॉगआउट

कोई बॉडी नहीं। सर्वर-साइड पर सेशन हटाता है — वास्तविक लॉगआउट पर इसे कॉल करें, केवल "स्थानीय रूप से टोकन भूलने" के बजाय, ताकि चोरी हुआ टोकन काम करना जारी न रखे।

GET/api/v1/auth/meसेशन टोकन · वैकल्पिक

वर्तमान उपयोगकर्ता

लॉग आउट होने पर { "user": null } लौटाता है (यह कभी त्रुटि नहीं होती) — ऐप स्टार्टअप पर लॉगिन स्क्रीन दिखानी है या नहीं, यह तय करने के लिए इसका उपयोग करें।

POST/api/v1/auth/forgot-passwordप्रमाणीकरण आवश्यक नहीं

पासवर्ड भूल गए

बॉडी: { email, locale }। पता मौजूद है या नहीं, इसकी परवाह किए बिना हमेशा { success: true } लौटाता है, ताकि खाता गणना को रोका जा सके। रीसेट लिंक/टोकन के साथ एक ईमेल भेजता है (1 घंटे के लिए मान्य)।

POST/api/v1/auth/reset-passwordप्रमाणीकरण आवश्यक नहीं

पासवर्ड रीसेट करें

बॉडी: { token, newPassword }। ?token= के साथ GET फॉर्म दिखाने से पहले वैधता जाँच सकता है ({ "valid": true|false })।

POST/api/v1/auth/change-passwordसेशन टोकन

पासवर्ड बदलें

बॉडी: { currentPassword, newPassword }। जब तक खाते में अभी तक पासवर्ड सेट न हो (जैसे सोशल लॉगिन), currentPassword आवश्यक है।

खाता

PATCH/api/v1/user/profileसेशन टोकन

प्रोफ़ाइल अपडेट करें

केवल वे फ़ील्ड भेजें जिन्हें आप बदलना चाहते हैं।

FieldNotes
firstName, lastNameवैकल्पिक · स्ट्रिंग
preferredCurrencyवैकल्पिक · USD, EUR, GBP, TRY में से एक
localeवैकल्पिक · दो-अक्षर कोड, जैसे hi
200 OK
{ "success": true, "user": { ...same shape as /auth/me } }
POST/api/v1/user/avatarसेशन टोकन

अवतार अपडेट करें

बॉडी: { "avatarUrl": "data:image/..." } — base64 data URI, अधिकतम ~1.5MB।

POST/api/v1/user/api-key/generateसेशन टोकन

API कुंजी जनरेट करें

इस खाते के लिए एक नई पार्टनर API कुंजी जारी करता है, पिछली कुंजी को बदलते हुए। मूल कुंजी केवल इस प्रतिक्रिया में एक बार दिखाई जाती है — बाद में केवल इसका उपसर्ग पुनर्प्राप्त किया जा सकता है।

200 OK
{
  "success": true,
  "key": "vio_live_sk_...",
  "apiKeyPrefix": "vio_live_sk_ab12…9f8e",
  "apiKeyGeneratedAt": "2026-08-22T17:00:00.781Z"
}
DELETE/api/v1/user/accountसेशन टोकन

खाता हटाएँ

App Store समीक्षा के लिए आवश्यक (खाता निर्माण वाले ऐप्स को इन-ऐप हटाने की सुविधा प्रदान करनी चाहिए)। पंक्तियों को स्थायी रूप से हटाने के बजाय खाते को गुमनाम बनाता है (ईमेल को घुमाया जाता है और पुनः पंजीकरण के लिए मुक्त किया जाता है, नाम/अवतार/पासवर्ड मिटा दिए जाते हैं), ताकि पिछले ऑर्डर कर/लेखांकन रिकॉर्ड के लिए बने रहें। उपयोगकर्ता के सभी सेशन और पंजीकृत पुश डिवाइस नष्ट कर देता है।

यदि walletBalance 0 से अधिक है तो 409 लौटाता है — ऐप को उपयोगकर्ता को चुपचाप धन खोने देने के बजाय पहले निकासी करने या सहायता से संपर्क करने के लिए प्रेरित करना चाहिए।

कैटलॉग

GET/api/v1/destinationsप्रमाणीकरण आवश्यक नहीं

गंतव्य सूची प्राप्त करें

वैध प्लान वाले देश और क्षेत्र, मूल्य निर्धारित और UI के लिए स्वरूपित (यह ठीक वही है जो स्टोरफ्रंट स्वयं कॉल करता है)। वैकल्पिक ?filter=popular|regional|global|<खोज टेक्स्ट>।

GET/api/v1/destinations/:codeप्रमाणीकरण आवश्यक नहीं

गंतव्य विवरण

ISO कोड द्वारा एक देश का पूरा विवरण (विवरण, प्लान), जैसे /api/v1/destinations/jp।

खरीदारी

POST/api/v1/checkoutसेशन टोकन

चेकआउट

पहले वॉलेट में फंड जोड़ने के बजाय सीधे एक प्लान खरीदता है।

FieldNotes
planId*
quantityवैकल्पिक · 1–10, डिफ़ॉल्ट 1
paymentMethod*wallet | stripe | crypto
successUrl, cancelUrlवैकल्पिक · stripe/crypto रीडायरेक्ट के लिए। रीडायरेक्ट को ऐप को फिर से खोलने के लिए साधारण वेब URL के बजाय यूनिवर्सल/ऐप लिंक का उपयोग करें।
200 OK — wallet (synchronous)
{ "success": true, "orderId": "..." }
200 OK — stripe / crypto (redirect required)
{ "success": true, "orderId": "...", "url": "https://checkout.stripe.com/..." }
url को साधारण WebView के बजाय इन-ऐप ब्राउज़र (SFSafariViewController / Chrome Custom Tabs) में खोलें — Stripe और Cryptomus दोनों को वास्तविक ब्राउज़र संदर्भ की आवश्यकता होती है।
POST/api/v1/payments/stripe/create-sessionसेशन टोकन

Stripe के माध्यम से वॉलेट जमा

कार्ड द्वारा वॉलेट में फंड जोड़ता है — यह चेकआउट से अलग प्रवाह है। बॉडी: { amount (सेंट में, न्यूनतम 200), currency, successUrl, cancelUrl }। { sessionId, url } लौटाता है।

POST/api/v1/payments/cryptomus/create-invoiceसेशन टोकन

क्रिप्टो के माध्यम से वॉलेट जमा

बॉडी: { amount (दशमलव स्ट्रिंग, न्यूनतम $2), currency, url_return }। url सहित एक Cryptomus इनवॉइस ऑब्जेक्ट लौटाता है।

GET/api/v1/user/ordersसेशन टोकन

ऑर्डर सूची

कॉलर के सभी ऑर्डर, नवीनतम से सबसे पुराने क्रम में लौटाता है।

GET/api/v1/user/orders/:idसेशन टोकन

ऑर्डर विवरण

esimIds के साथ एकल ऑर्डर — पूर्ण eSIM विवरण (QR, सक्रियण कोड) प्राप्त करने के लिए GET /api/v1/user/esims का उपयोग करें और id द्वारा मिलान करें।

GET/api/v1/user/esimsसेशन टोकन

मेरे eSIM

कॉलर के स्वामित्व वाला प्रत्येक eSIM: iccid, activationCode, qrCodeUrl, smdpAddress, status, dataUsage/totalVolume (MB में), activatedAt, expiresAt। यह "मेरे eSIM" स्क्रीन और QR डिस्प्ले को संचालित करने वाला डेटा है।

GET/api/v1/user/wallet/transactionsसेशन टोकन

वॉलेट इतिहास

/auth/me में दिखाए गए वॉलेट बैलेंस के पीछे जमा/निकासी/खरीद/धनवापसी इतिहास।

सहायता

GET/api/v1/support/ticketsसेशन टोकन

टिकट सूची

कॉलर के टिकट और उनके पूर्ण संदेश थ्रेड, नवीनतम से सबसे पुराने क्रम में।

POST/api/v1/support/ticketsसेशन टोकन

नया टिकट

बॉडी: { subject, category, message } (category वैकल्पिक है)।

POST/api/v1/support/tickets/:id/messagesसेशन टोकन

टिकट का जवाब दें

बॉडी: { message }। RESOLVED/CLOSED टिकट का जवाब देने से यह स्वचालित रूप से फिर से खुल जाता है।

पुश नोटिफिकेशन डिवाइस

यह केवल डिवाइस टोकन पंजीकरण संभालता है — वास्तविक भेजने के लिए APNs/FCM क्रेडेंशियल की आवश्यकता होती है। नीचे नोट देखें।

POST/api/v1/user/push-devicesसेशन टोकन

डिवाइस पंजीकृत करें

APNs या FCM टोकन प्राप्त करने के बाद कॉल करें। बॉडी: { platform: "IOS"|"ANDROID", pushToken, appVersion }। यह टोकन द्वारा अपसर्ट किया जाता है, इसलिए हर ऐप स्टार्टअप पर फिर से कॉल करना सुरक्षित और अनुशंसित है (टोकन घूम सकते हैं)।

DELETE/api/v1/user/push-devicesसेशन टोकन

डिवाइस पंजीकरण रद्द करें

बॉडी: { pushToken }। लॉगआउट पर कॉल करें ताकि साझा/रीसेट किए गए डिवाइस अन्य उपयोगकर्ताओं की सूचनाएँ प्राप्त करना जारी न रखें।

पार्टनर API

नीचे दिए गए सभी एंडपॉइंट के लिए ऊपर बताए गए API कुंजी हेडर की आवश्यकता है — यहाँ सेशन कुकीज़ लागू नहीं होतीं।

कैटलॉग

GET/api/public/v1/destinationsAPI कुंजी

गंतव्य सूची प्राप्त करें

स्टोरफ्रंट के UI प्रारूप के बजाय पार्टनर-उन्मुख प्रारूप में पूरा कैटलॉग।

200 OK
{
  "countries": [
    {
      "code": "JP",
      "name": { "en": "Japan", "tr": "Japonya", "...": "..." },
      "flagEmoji": "🇯🇵",
      "continent": "Asia",
      "plans": [
        { "id": "cus...", "dataAmountMb": 1024, "durationDays": 7, "priceUsd": 4.25, "isTopUp": false }
      ]
    }
  ],
  "regions": [ { "code": "...", "name": {...}, "countryCount": 15, "plans": [...] } ]
}
GET/api/public/v1/destinations/:codeAPI कुंजी

गंतव्य विवरण

ISO कोड द्वारा एक देश (जैसे /api/public/v1/destinations/JP), प्लान प्रारूप ऊपर जैसा ही।

ऑर्डर

POST/api/public/v1/ordersAPI कुंजी

ऑर्डर बनाएँ

कॉलर के वॉलेट बैलेंस से एक प्लान खरीदता है और eSIM को समकालिक रूप से प्रावधानित करता है — प्रतिक्रिया में पहले से ही QR/सक्रियण डेटा शामिल है जो अंतिम ग्राहक को सौंपने के लिए तैयार है। सामान्य मामले में कोई पोलिंग आवश्यक नहीं है।

Request body
{ "planId": "cus...", "quantity": 1 }
201 Created
{
  "id": "...", "orderNumber": "VIO-API-...", "status": "COMPLETED", "amountUsd": 4.25,
  "esims": [
    { "id": "...", "iccid": "...", "activationCode": "...",
      "qrCodeUrl": "https://...", "smdpAddress": "...", "status": "PENDING" }
  ]
}
विफलता मोड: 402 INSUFFICIENT_BALANCE (पहले फंड जोड़ें), 404 PLAN_NOT_FOUND, या 502 FULFILLMENT_FAILED (शुल्क लिया गया लेकिन प्रदाता eSIM जारी करने में विफल — ऑर्डर id शामिल है, सहायता को स्वचालित रूप से सूचित किया जाता है। फिर से शुल्क न लें, GET /orders/:id को पोल करें)।
GET/api/public/v1/ordersAPI कुंजी

ऑर्डर सूची

वैकल्पिक ?limit= (डिफ़ॉल्ट 25, अधिकतम 100)। यह सारांश प्रारूप है — eSIM डेटा के लिए विवरण एंडपॉइंट का उपयोग करें।

GET/api/public/v1/orders/:idAPI कुंजी

ऑर्डर विवरण

प्रत्येक eSIM के लिए QR/सक्रियण डेटा और वास्तविक समय उपयोग (dataUsageMb / totalVolumeMb) के साथ पूर्ण ऑर्डर विवरण — ग्राहक को शेष डेटा दिखाने के लिए इसे पोल करें।

वॉलेट

GET/api/public/v1/walletAPI कुंजी

वॉलेट बैलेंस

बल्क ऑर्डर देने से पहले जाँचें, या बैलेंस कम होने पर स्वयं को सचेत करने के लिए इसका उपयोग करें।

200 OK
{ "balanceUsd": 128.40, "currency": "USD" }

अभी तक नहीं बनाया गया

ताकि यहाँ न होने वाली किसी चीज़ को काम करने वाली न समझा जाए।

पुश नोटिफिकेशन भेजना

टोकन पंजीकरण काम करता है; वास्तविक भेजने के लिए APNs/FCM क्रेडेंशियल की आवश्यकता है।

पार्टनर-विशिष्ट मूल्य निर्धारण

पार्टनर API वर्तमान में स्टोरफ्रंट के समान खुदरा मूल्य लेता है। थोक/परक्राम्य मूल्य निर्धारण के लिए स्कीमा परिवर्तन और व्यावसायिक निर्णय की आवश्यकता है।

रिफ्रेश टोकन

सेशन एक अल्पकालिक एक्सेस + रिफ्रेश टोकन जोड़ी के बजाय एक दीर्घकालिक (30-दिवसीय) फ्लैट टोकन है। अभी के लिए पर्याप्त है; यदि अधिक सख्त सुरक्षा व्यवस्था की आवश्यकता हो तो बाद में पुनर्मूल्यांकन करें।

नेटिव Stripe भुगतान स्क्रीन

Stripe एकीकरण वर्तमान में होस्टेड Checkout (रीडायरेक्ट/वेबव्यू) का उपयोग करता है। नेटिव कार्ड-एंट्री UI के लिए PaymentIntents + Stripe SDK की आवश्यकता होगी।

पार्टनर के लिए Webhook

पार्टनर को स्थिति के लिए वर्तमान में GET /orders/:id को पोल करना होगा। अभी तक कोई आउटबाउंड webhook (जैसे "eSIM सक्रिय हो गया") उपलब्ध नहीं है।

एकीकरण के बारे में प्रश्न हैं? [email protected] पर संपर्क करें
Vio eSIM API संदर्भ और पार्टनर API दस्तावेज़