SMM पैनल API के मेथड: add, status, refill और cancel

जब आप पैनल को किसी बॉट, अपनी साइट या दूसरे पैनल से जोड़ते हैं, तो «API क्या है» वाला सामान्य विवरण बेकार हो जाता है - आपको कॉल की ठीक सूची, उनके पैरामीटर और जवाब के ढाँचे चाहिए। यह संदर्भ आम दस्तावेज़ों से अलग तरीक़े से बनाया गया है: असली अनुबंध हमने ग्यारह चालू पैनलों पर नापा और अपने कोर से मिलाकर देखा। नीचे सभी दस कॉल हैं, सेवा के प्रकार के हिसाब से ऑर्डर के फ़ील्ड, और वे तीन जगहें जहाँ इंटीग्रेशन सबसे ज़्यादा टूटते हैं।

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

लगभग हर पैनल एक ही API क्यों बोलता है

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

सब पर लागू ठीक चार नियम हैं:

• एक ही एंडपॉइंट। आम तौर पर /api/v2, मेथड हमेशा POST, जवाब हमेशा JSON।
• कुंजी हेडर नहीं, फ़ील्ड है। वह सामान्य key पैरामीटर की तरह जाती है - न Authorization, न Bearer।
• क्रिया action में रहती है। न रास्ता, न HTTP मेथड - क्या होगा यह उसी फ़ील्ड का मान तय करता है।
• पथ के बाहर कोई वर्ज़निंग नहीं। «v2» एंडपॉइंट का हिस्सा है, हेडर या पैरामीटर नहीं।

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

सात action, दस कॉल

मानक में सात action हैं, पर उनमें चार बैच रूप में भी आते हैं - इससे समर्थन के लिए दस अलग कॉल बनती हैं:

• action=services - सेवाओं की सूची। service (सार्वजनिक नंबर), name, type, category, rate, min, max, refill, cancel वाला ऐरे लौटाता है।
• action=add - ऑर्डर बनाना। service हमेशा ज़रूरी है; बाक़ी फ़ील्ड सेवा के प्रकार पर निर्भर हैं। जवाब {"order": 23501}।
• action=status के साथ order - एक ऑर्डर: charge, start_count, status, remains, currency।
• action=status के साथ orders - एक ही रिक्वेस्ट में कॉमा से अलग किए सौ तक नंबर।
• action=refill के साथ order - refill बनाना। जवाब refill का नंबर है, अक्सर स्ट्रिंग के रूप में: {"refill": "1"}।
• action=refill के साथ orders - बैच refill, सौ तक ऑर्डर।
• action=refill_status के साथ refill - refill की अपनी संख्या से उसकी स्थिति।
• action=refill_status के साथ refills - वही थोक में।
• action=cancel के साथ orders - रद्द करना, दस्तावेज़ में सिर्फ़ बैच रूप में।
• action=balance - {"balance": "100.84292", "currency": "USD"}।

इस सूची के बाहर जो कुछ है वह किसी एक पैनल का विस्तार है। हमारा, उदाहरण के लिए, order से एक अकेला cancel स्वीकार करता है और action=create को add का पर्याय मानता है - पर क्लाइंट ऐसी सुविधाओं के भरोसे कभी नहीं लिखा जाना चाहिए, क्योंकि अगले पैनल पर वे नहीं होंगी।

ऑर्डर के फ़ील्ड सेवा के प्रकार पर निर्भर हैं

पहले इंटीग्रेशन की सबसे बड़ी ग़लतफ़हमी यह है कि ऑर्डर एक लिंक और एक मात्रा है। यह सिर्फ़ आधार प्रकार है। services में type फ़ील्ड स्ट्रिंग नाम के रूप में आता है, और add का पूरा पैरामीटर सेट वही तय करता है:

• Default - link और quantity, धीरे-धीरे डिलीवरी के लिए वैकल्पिक runs और interval।
• Custom Comments - link और comments: मात्रा भेजी ही नहीं जाती, वह सूची की पंक्तियों से निकलती है।
• Mentions परिवार - छह अलग प्रकार, जिनमें फ़र्क़ सिर्फ़ इसका है कि ऑडियंस कहाँ से आती है: तैयार usernames सूची, कोई hashtag, किसी और खाते के फ़ॉलोअर, या किसी ख़ास पोस्ट को लाइक करने वाले।
• SEO मात्रा के साथ keywords लेता है; Poll लेता है answer_number, यानी जिस विकल्प पर वोट देना है उसका क्रमांक।
• Package - सिर्फ़ link: न मात्रा, न अतिरिक्त फ़ील्ड, मात्रा ख़ुद सेवा में बँधी है।
• Subscriptions - link नाम की कोई चीज़ नहीं। उसकी जगह username, min और max सीमाएँ, मिनटों की बंद सूची से एक delay, और d/m/Y प्रारूप में एक expiry तारीख़।
• Web Traffic - इनमें सबसे चौड़ा: country, device, type_of_traffic, तीनों शब्द नहीं, किसी लुकअप तालिका से आए नंबर के रूप में। कीवर्ड ट्रैफ़िक को अतिरिक्त google_keyword चाहिए, कस्टम रेफ़रर को referring_url।

दो तकनीकी बातें लगभग सबको गिरा देती हैं। सूचियाँ - कमेंट, कीवर्ड, यूज़रनेम, हैशटैग - JSON ऐरे के रूप में नहीं, बल्कि नई पंक्ति को विभाजक मानकर एक ही स्ट्रिंग के रूप में भेजी जाती हैं। और device तथा type_of_traffic के पीछे के संख्यात्मक मान services में कभी नहीं लौटते: वे मान आपको पैनल के दस्तावेज़ से पहले से पता होने चाहिए।

एक बात साफ़ मान लेने लायक़ है: प्रकारों की संख्या में छेद हैं। कम से कम छह नंबर इंजनों को पता हैं पर हमारे नापे किसी पैनल में नहीं दिखते। इसलिए «हम हर प्रकार सपोर्ट करते हैं» ऐसा वादा है जो कोई निभा नहीं सकता - लेने वाले पैनल के लिए सही रणनीति है अनजाने प्रकार पर फ़ील्ड का अंदाज़ा लगाने के बजाय साफ़ इनकार। प्रकारों का असल मतलब प्रोवाइडर की सेवा किस्में में खोला गया है।

वे तीन जगहें जहाँ इंटीग्रेशन टूटते हैं

ये तीनों लगभग किसी दस्तावेज़ सेट में नहीं हैं, और ठीक वही उन बग को जन्म देते हैं जो शुरुआत के हफ़्ते भर बाद सतह पर आते हैं।

• बैच जवाब का ढाँचा action पर निर्भर है। status के लिए यह ऑर्डर नंबर से कुंजीबद्ध एक ऑब्जेक्ट है। refill, refill_status और cancel के लिए यह ऑब्जेक्ट का ऐरे है, जिसमें नंबर हर तत्व के भीतर होता है। सभी बैच जवाबों के लिए एक पार्सर नहीं चलेगा।
• प्रति-तत्व त्रुटियाँ भीतर नेस्टेड आती हैं। पूरी रिक्वेस्ट के लिए {"error": ...} के रूप में नहीं, बल्कि ख़ुद तत्व के भीतर, उसी कुंजी के नीचे जिसे नतीजा इस्तेमाल करता। जो कोड सिर्फ़ ऊपरी स्तर पढ़ता है वह सौ में से निन्यानबे ऑर्डर संभाल लेगा और सौवाँ चुपचाप खो देगा।
• refill का पता उसकी अपनी संख्या से चलता है, ऑर्डर की नहीं। action=refill refill नंबर लौटाता है, और refill_status उसे सिर्फ़ उसी से ढूँढ़ता है। API में ऑर्डर और refill के बीच कोई जोड़ ही नहीं है: वह नंबर सहेजना क्लाइंट का काम है। कुछ पैनल वहाँ विस्तार के रूप में ऑर्डर नंबर भी स्वीकार करते हैं - हमारा करता है, ताकि मौजूदा इंटीग्रेशन चलते रहें - पर मानक में ऐसा कुछ नहीं।

रद्द करना भी इसी सूची का है: मानक में एक ऑर्डर वाला cancel नहीं है, सिर्फ़ बैच वाला। जो क्लाइंट ऑर्डर एक-एक करके रद्द करता है उसे भी एक तत्व की सूची भेजनी पड़ती है और बदले में ऐरे पार्स करना पड़ता है।

स्टेटस और त्रुटियाँ स्थिरांक नहीं, स्ट्रिंग हैं

ऑर्डर का स्टेटस पढ़े जा सकने वाले टेक्स्ट के रूप में आता है: Pending, In progress, Processing, Partial, Completed, Canceled, Fail, Error। refill के अपने मान हैं - Completed, Rejected और बीच का In progress - और अनजान refill नंबर पर Refill not found लौटता है।

इससे क्लाइंट के लिए चार नियम बनते हैं:

• तुलना बड़े-छोटे अक्षर की परवाह किए बिना कीजिए और स्पेस पर मत टिकिए: अलग पैनल एक ही स्थिति को थोड़ा अलग लिखते हैं।
• अनजान स्टेटस विफलता नहीं है। उसका मतलब है «कुछ नहीं बदला, बाद में फिर पूछो», न कि «ऑर्डर मर गया»। वरना जिस दिन कोई पैनल अपने मान बढ़ाएगा, आपको झूठे रिफ़ंड की बाढ़ मिलेगी।
• पैसे को स्ट्रिंग के रूप में पार्स कीजिए। charge और balance चार दशमलव अंकों वाली स्ट्रिंग के रूप में आते हैं - float से गुज़ारना उन्हें किसी और के फ़ायदे में गोल कर देता है।
• रिक्वेस्ट स्तर की त्रुटियाँ भी स्ट्रिंग हैं: Incorrect API key, Incorrect order ID, Incorrect action। HTTP कोड 200 भी रह सकता है, इसलिए सिर्फ़ कोड जाँचना काफ़ी नहीं।

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

प्रोडक्शन से पहले इंटीग्रेशन कैसे परखें

छह जाँचें, जो पहले असली ऑर्डर से पहले लगभग सब पकड़ लेती हैं:

• services चलाइए और आ रहे प्रकारों को अपने कोड द्वारा संभाले जाने वाले प्रकारों से मिलाइए। अनजान प्रकार पर साफ़ इनकार निकलना चाहिए, ख़ाली फ़ील्ड वाला ऑर्डर नहीं।
• हर उस प्रकार का एक ऑर्डर दीजिए जिसे आप बेचने वाले हैं। फ़ील्ड सेट की ग़लतियाँ सिर्फ़ इसी तरह दिखती हैं, क्योंकि पैनल की तरफ़ की जाँच सख़्त होती है।
• सौ नंबरों पर बैच status, जिनमें एक ज़रूर ऐसा हो जो मौजूद ही नहीं। यही नेस्टेड-त्रुटि का परीक्षण है - जिसके बिना ऑर्डर एक-एक करके खोते हैं।
• पूरा refill चक्र: refill, नंबर सहेजिए, refill_status उसी refill नंबर से पूछिए। अगर आपका कोड ऑर्डर नंबर से पूछता है और फिर भी जवाब पाता है, तो आप किसी एक पैनल के विस्तार पर टिके हैं।
• ग़लत कुंजी। जवाब फिर भी JSON होना चाहिए। HTML आए तो आपके सामने API नहीं, वेब सर्वर का एरर पेज है, और आपके क्लाइंट को यह फ़र्क़ पहचानना ही होगा - वरना पैनल की तरफ़ की गड़बड़ी हर ऑर्डर के इनकार जैसी दिखेगी।
• पोलिंग की दर। सौ तक के बैच, प्रति ऑर्डर मिनट में एक से ज़्यादा नहीं, और हर विफलता के बाद बढ़ता विराम। पूरे हो चुके ऑर्डर कभी पोल मत कीजिए - बेवजह रेट लिमिट से टकराने का यह सबसे आम तरीक़ा है।

प्रोवाइडर की तरफ़ अतिरिक्त काम है: प्रति कुंजी सीमाएँ, कॉल का लॉग और एक ही ऑर्डर दो बार जाने से बचाव। रीसेलर को कुंजी देने से पहले क्या जाँचें, यह प्रोवाइडर के रूप में SMM सेवाएँ कैसे बेचें में है। आपका अपना प्रोवाइडर हमारी तरफ़ समर्थित है या नहीं, यह प्रोवाइडर जाँच पेज पर देख सकते हैं।

निचोड़

API v2 सरल दिखता है - एक एंडपॉइंट, सात action - और ठीक इसीलिए इसे कम आँका जाता है। असली जटिलता तीन जगहों पर बैठी है: सेवा का प्रकार ऑर्डर के फ़ील्ड तय करता है, बैच जवाब का ढाँचा action पर निर्भर है, और refill अपनी अलग संख्या के नीचे रहता है। जो क्लाइंट इन तीनों का लिहाज़ करता है वह पैनलों के बीच लगभग बिना बदलाव चला जाता है; जो इन्हें चूक गया वह ऑर्डर चुपचाप खोता है।

अगर आपको API किसी और के पैनल का नहीं, अपने पैनल का चाहिए, तो यह सब बिना पैसे लगाए परखा जा सकता है: हमारे अपने कैटलॉग से गए ऑर्डर, चाहे जितने हों, कभी बिल में नहीं आते, और तीसरे पक्ष के प्रोवाइडर पर महीने के पहले 100 ऑर्डर मुफ़्त हैं। कुंजी और पूरा दस्तावेज़ तुरंत मिल जाते हैं, इसलिए पैनल का पहला ग्राहक आने से पहले ही आप क्लाइंट लिखकर दसों कॉल चला सकते हैं। वह सीमा कैसे गिनी जाती है, यह किराए का प्लान कैसे गिना जाता है में समझाया है।