REST API v2

अवलोकन

यह वह सरफ़ेस है जिसे एक AI एजेंट चलाता है। हर कॉल एक वर्ब है जिसे action चुनता है, इसलिए एजेंट कैटलॉग खोजता है, दर और सीमाएँ पढ़ता है, फिर कार्य करता है. search-then-act, कोई पैसा हिलने से पहले दाम की पुष्टि के साथ। MCP सर्वर और CLI इन्हीं कॉल को रैप करते हैं; यह पेज उसके नीचे का कच्चा प्रोटोकॉल है।

यह API व्यापक रूप से अपनाए गए SMM API v2 स्वरूप का पालन करता है, इसलिए मौजूदा पैनल सॉफ़्टवेयर, स्क्रिप्ट और एजेंट एकीकरण न्यूनतम बदलावों के साथ काम करते हैं। हर ऑपरेशन एक एकल एंडपॉइंट से होकर गुज़रता है और action पैरामीटर से वर्ब चुनता है। प्रतिक्रियाएँ JSON में होती हैं. किसी स्क्रिप्ट या LLM के लिए पार्स और चेन करना आसान।

एंडपॉइंट

POST https://api.socialgo.com/api/v2

प्रमाणीकरण

प्रमाणीकरण प्रति-अनुरोध होता है. कोई सेशन नहीं, कोई हैंडशेक नहीं, और यही इसे एक एजेंट द्वारा कॉल करने योग्य बनाता है। हर कॉल पर अपनी गुप्त key भेजें। इसे डैशबोर्ड में Account → API के अंतर्गत पाएँ और बदलें। key को पासवर्ड की तरह मानें: इसे सर्वर-साइड रखें, कभी क्लाइंट कोड या एजेंट प्रॉम्प्ट में नहीं।

अनुरोध प्रारूप

POST के ज़रिए application/x-www-form-urlencoded फ़ॉर्म पैरामीटर भेजें। हर प्रतिक्रिया JSON में होती है। हर कॉल पर दो पैरामीटर होते हैं:

• key. आपकी API key (आवश्यक)
• action. चलाया जाने वाला वर्ब (आवश्यक)

त्रुटि प्रारूप

विफलता पर प्रतिक्रिया में मानव-पठनीय संदेश के साथ एक error फ़ील्ड होती है, और HTTP स्टेटस समस्या को दर्शाता है (उदा. 400 ख़राब अनुरोध, 401 अमान्य key)। एक पूर्वानुमेय स्वरूप, ताकि कोई स्क्रिप्ट या एजेंट बिना अंदाज़ा लगाए इस पर ब्रांच कर सके।

{
  "error": "Incorrect request"
}

एक्शन

हर वर्ब एक काम करता है। एक एजेंट उन्हें क्रम में चेन करता है: क्या ख़रीदना है यह ढूँढने के लिए services, ख़रीदने के लिए add, ट्रैक करने के लिए status. रीड कॉल (services, status, balance) उसे राइट कॉल (add, refill, cancel) के कुछ भी खर्च करने से पहले दाम और धनराशि की पुष्टि करने देते हैं।

1. सेवा सूची

वह कैटलॉग जिसे एजेंट सबसे पहले पढ़ता है: हर वह सेवा जिसे वह ऑर्डर कर सकता है, सेवा ID, श्रेणी, दर (प्रति 1000 मूल्य) और न्यूनतम/अधिकतम परिमाण के साथ। ऑर्डर देने के लिए वह लौटाई गई service IDs का उपयोग करता है. और खर्च से पहले लागत की पुष्टि के लिए दर का।

अनुरोध

key=YOUR_API_KEY
action=services

प्रतिक्रिया

[
  {
    "service": 1,
    "name": "Instagram Followers",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.90",
    "min": "50",
    "max": "10000",
    "refill": true,
    "cancel": true
  },
  {
    "service": 2,
    "name": "Instagram Likes",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.40",
    "min": "10",
    "max": "20000",
    "refill": false,
    "cancel": true
  }
]

2. ऑर्डर जोड़ें

राइट कॉल। एक सेवा के लिए ऑर्डर देता है. service ID, लक्ष्य link और quantity पास करें। प्रतिक्रिया ट्रैक करने हेतु नई order ID लौटाती है। एक एजेंट इसे तभी चलाता है जब वह दर और सीमाओं की पुष्टि कर चुका हो।

पैरामीटर

• service. सेवा सूची से सेवा ID
• link, पोस्ट/प्रोफ़ाइल/चैनल का URL
• quantity. डिलीवर की जाने वाली इकाइयों की संख्या

अनुरोध

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000

प्रतिक्रिया

{
  "order": 23501
}

3. ऑर्डर जोड़ें, ड्रिप-फ़ीड

एक ऑर्डर को समय के साथ फैली छोटी डिलीवरी में बाँट देता है, एक स्थिर वक्र के लिए। runs (कितनी डिलीवरी) और interval (हर एक के बीच मिनट) सेट करें। कुल डिलीवरी quantity × runs होती है. वही गणित जिससे एक एजेंट बिना आपके हाथ से किए अभियान का आकार तय करता है।

अतिरिक्त पैरामीटर

• runs. डिलीवरी रन की संख्या
• interval. हर रन के बीच मिनट

अनुरोध

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000
runs=10
interval=60

प्रतिक्रिया

{
  "order": 23502
}

4. ऑर्डर स्थिति

एक ऑर्डर की वर्तमान स्थिति लौटाता है: शुल्क, आरंभिक गणना, स्थिति, शेष परिमाण और मुद्रा। इसी तरह एक एजेंट बिना आपके डैशबोर्ड रीफ़्रेश किए ऑर्डर पर नज़र रखता है. और रिफिल के लिए फ़्लैग करने लायक गिरावट को पहचानता है।

अनुरोध

key=YOUR_API_KEY
action=status
order=23501

प्रतिक्रिया

{
  "charge": "0.90",
  "start_count": "4250",
  "status": "In progress",
  "remains": "200",
  "currency": "USD"
}

संभावित status मान: Pending, In progress, Processing, Completed, Partial, Canceled.

5. एकाधिक ऑर्डर स्थिति

एक ही कॉल में कई ऑर्डर जाँचें. orders पैरामीटर में अल्पविराम से अलग की गई IDs की सूची पास करें। प्रतिक्रिया ऑर्डर ID द्वारा कुंजीबद्ध होती है, ताकि एक एजेंट प्रति ऑर्डर एक कॉल के बजाय पूरे अभियान को एक ही राउंड ट्रिप में पोल कर सके।

अनुरोध

key=YOUR_API_KEY
action=status
orders=23501,23502,23503

प्रतिक्रिया

{
  "23501": {
    "charge": "0.90",
    "start_count": "4250",
    "status": "Completed",
    "remains": "0",
    "currency": "USD"
  },
  "23502": {
    "charge": "9.00",
    "start_count": "1200",
    "status": "In progress",
    "remains": "500",
    "currency": "USD"
  },
  "23503": {
    "error": "Incorrect order ID"
  }
}

6. रीफ़िल

ऐसे ऑर्डर पर रीफ़िल का अनुरोध करता है जिसकी सेवा इसका समर्थन करती है (सेवा सूची में refill: true) और ट्रैक करने हेतु एक रीफ़िल ID लौटाता है। एक एकल order या अल्पविराम से अलग की गई orders सूची पास करें. ताकि स्टेटस जाँच में गिरावट दिखने पर एजेंट थोक में रीफ़िल का अनुरोध कर सके।

अनुरोध (एकल)

key=YOUR_API_KEY
action=refill
order=23501

प्रतिक्रिया

{
  "refill": 4001
}

अनुरोध (एकाधिक)

key=YOUR_API_KEY
action=refill
orders=23501,23502

प्रतिक्रिया

[
  { "order": 23501, "refill": 4001 },
  { "order": 23502, "refill": { "error": "Refill not available" } }
]

7. रद्द करें

ऐसे ऑर्डर रद्द करने का अनुरोध करता है जिन्हें अभी प्रोसेस नहीं किया गया (cancel: true वाली सेवाएँ)। अल्पविराम से अलग की गई orders सूची पास करें; प्रतिक्रिया प्रति ऑर्डर परिणाम रिपोर्ट करती है। वही अंडू जिसे एक एजेंट तब इस्तेमाल करता है जब कुछ ग़लती से कतार में लग जाए।

अनुरोध

key=YOUR_API_KEY
action=cancel
orders=23501,23502

प्रतिक्रिया

[
  { "order": 23501, "cancel": 1 },
  { "order": 23502, "cancel": { "error": "Incorrect order ID" } }
]

8. बैलेंस

आपका खाता बैलेंस और मुद्रा लौटाता है। एक एजेंट ऑर्डर देने से पहले खर्च को नियंत्रित करने के लिए इसे पढ़ता है. और आपका अपना पैनल धनराशि दिखाने के लिए। खर्च करने को पैसा है या नहीं, यह पुष्टि करने वाली सबसे सस्ती कॉल।

अनुरोध

key=YOUR_API_KEY
action=balance

प्रतिक्रिया

{
  "balance": "182.45",
  "currency": "USD"
}

इसे किसी भी चीज़ से कॉल करें

एक एंडपॉइंट, सादे फ़ॉर्म पैरामीटर. ताकि एक शेल, एक क्रॉन जॉब, या एक एजेंट इसे एक ही तरह चला सके। कमांड लाइन से दिया गया एक पूर्ण ऑर्डर यहाँ है:

curl -X POST https://api.socialgo.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=1" \
  -d "link=https://instagram.com/example" \
  -d "quantity=1000"

टिप्पणियाँ और सर्वोत्तम अभ्यास

• लिखने से पहले पढ़ें। दर, सीमाएँ और धनराशि पुष्ट करने के लिए services (या balance) कॉल करें, फिर add कॉल करें. वही search-then-act गार्डरेल जिसका इस्तेमाल डैशबोर्ड और MCP सर्वर करते हैं ताकि बिना पुष्ट दाम के कुछ भी खर्च न हो।
• सेवा सूची को कैश करें और समय-समय पर रीफ़्रेश करें. IDs, दरें और सीमाएँ बदलती हैं।
• अस्वीकृत कॉल से बचने के लिए ऑर्डर सबमिट करने से पहले min/max परिमाण की पुष्टि करें।
• प्रति ऑर्डर एक अनुरोध के बजाय एकाधिक-ऑर्डर कॉल के साथ बैचों में स्टेटस पोल करें।
• अपनी key को सर्वर-साइड रखें। यदि यह कभी उजागर हो जाए, तो उसे डैशबोर्ड से तुरंत बदल दें।