पार्टनर API

पार्टनरों के लिए सर्वर-से-सर्वर API: कुंजी बनाएँ, स्टोरफ़्रंट कॉन्फ़िगरेशन और लोकेशन पढ़ें, ग्राहक बनाएँ, प्लान दें और अपनी वेबसाइट या Telegram बॉट से सब्सक्रिप्शन लिंक प्रबंधित करें।

पार्टनर API से आप CreateYourVPN के ऊपर अपनी वेबसाइट, अपना डैशबोर्ड या Telegram बॉट बना सकते हैं।

API में ग्राहक, सब्सक्रिप्शन, प्लान और स्टोरफ़्रंट कॉन्फ़िगरेशन शामिल हैं। सर्वर, नोड, पैनल और SSH क्रेडेंशियल जैसा इंफ्रास्ट्रक्चर सार्वजनिक कॉन्ट्रैक्ट के बाहर है।

केवल सर्वर-से-सर्वर। API कुंजियाँ अपने सर्वर पर रखें और उन्हें frontend कोड में न डालें। ब्राउज़र हेडर वाले अनुरोध 403 browser_forbidden के साथ अस्वीकार कर दिए जाते हैं।

कुंजी पाना

डैशबोर्ड खोलें → अकाउंट मेनू → «API», «कुंजियाँ» टैब।

कुंजी को एक नाम दें (Telegram बॉट, लैंडिंग पेज) और सिर्फ़ वही अनुमतियाँ चुनें जिनकी उसे ज़रूरत है।

«कुंजी बनाएँ» चुनें और पूरा मान कॉपी करें। secret एक बार ही दिखाया जाता है, क्योंकि सिर्फ़ उसका hash सहेजा जाता है।

हर पार्टनर के पास अधिकतम 5 सक्रिय कुंजियाँ हो सकती हैं। कुंजी बदलने के लिए नई कुंजी बनाएँ, इंटीग्रेशन अपडेट करें और फिर पुरानी कुंजी रद्द करें।

प्रमाणीकरण

कुंजी को bearer टोकन के रूप में भेजें:

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

X-API-Key: cyv_live_… भी काम करता है, उन स्थितियों के लिए जहाँ Authorization को कोई proxy इस्तेमाल कर रहा हो।

कुंजी ऐसी दिखती है: cyv_live_<key_id>_<secret>। पहला हिस्सा (key_id) सार्वजनिक है: यही आप डैशबोर्ड में देखते हैं, और इसे सपोर्ट को बेझिझक बता सकते हैं। दूसरा हिस्सा secret है।

अनुमतियाँ (scopes)

अनुमति	क्या करने देती है
`config:read`	स्टोरफ़्रंट कॉन्फ़िगरेशन, प्लान, लोकेशन और `/me` पढ़ना।
`users:read`	ग्राहकों, उनके सब्सक्रिप्शन और ट्रैफ़िक को पढ़ना।
`users:write`	ग्राहक बनाना, प्लान देना, सब्सक्रिप्शन लिंक रीसेट करना, ग्राहक हटाना।

config:read उन इंटीग्रेशन के लिए काफ़ी है जो सिर्फ़ स्टोरफ़्रंट का डेटा पढ़ते हैं। users:read या users:write तभी जोड़ें, जब इंटीग्रेशन को ग्राहकों से जुड़े संबंधित ऑपरेशन चाहिए हों।

पूरा, चलाने योग्य कॉन्ट्रैक्ट सार्वजनिक Postman कलेक्शन में है। इसमें हर endpoint, अनुमति, पैरामीटर, अनुरोध का body, जवाब का उदाहरण और स्थिर त्रुटि कोड है। कलेक्शन backend कॉन्ट्रैक्ट से बनता है और अनुरोधों व जवाबों की स्कीमा का मौजूदा स्रोत है।

सार्वजनिक Postman कलेक्शन खोलें

हर endpoint देखें और कलेक्शन को अपने workspace में कॉपी करें।

रेट लिमिट

लिमिट हर कुंजी के लिए अलग से गिनी जाती हैं, अनुरोध के IP पते से स्वतंत्र रूप से।

कुल मिलाकर हर कुंजी पर 120 अनुरोध प्रति मिनट।
ख़ास तौर पर GET /users के लिए 10 अनुरोध प्रति मिनट।

GET /users की लिमिट अलग है, क्योंकि हर अनुरोध ग्राहकों की पूरी सूची लोड करता है। नियमित जाँच के लिए GET /users/{id} या externalId से खोज का उपयोग करें।

सुझाया गया तरीका। बनाते समय लौटाई गई CreateYourVPN ग्राहक ID सहेजें और आगे की जाँच के लिए GET /users/{id} का उपयोग करें। आप इसे externalId के ज़रिए अपने पहचानकर्ता से जोड़ सकते हैं।

आइडेम्पोटेंसी (Idempotency)

तीन ऑपरेशन के लिए Idempotency-Key हेडर ज़रूरी है: प्लान देना, सब्सक्रिप्शन लिंक रीसेट करना और ग्राहक हटाना।

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

एक ही कुंजी के साथ 24 घंटे के भीतर अनुरोध दोहराने पर ऑपरेशन फिर से चलाने के बजाय सहेजा हुआ जवाब लौटता है। इससे timeout के बाद इंटीग्रेशन के दोबारा कोशिश करने पर दोहरे बदलाव नहीं होते।

हर बिज़नेस इवेंट (जैसे एक भुगतान या एक कार्रवाई) के लिए एक कुंजी बनाएँ और उस इवेंट की हर दोबारा कोशिश में उसी का उपयोग करें।

अगर पहली कोशिश अभी चल रही है या उसका नतीजा अस्थायी रूप से पता नहीं है, तो API ऑपरेशन दोबारा किए बिना 409 conflict लौटाता है। दोबारा कोशिश करने का फ़ैसला करने से पहले ग्राहक की मौजूदा स्थिति जाँचें।

अनुरोधों और जवाबों की स्कीमा के लिए ऊपर दिए सार्वजनिक Postman कलेक्शन को ही सही स्रोत मानें।