SMSCode API गाइड — डेवलपर के लिए पूरी जानकारी

आज के दौर में किसी भी आधुनिक अनुप्रयोग में SMS वेरिफिकेशन एक बुनियादी ज़रूरत बन चुकी है — अकाउंट साइनअप, दो-चरण वेरिफिकेशन, पासवर्ड रिकवरी। लेकिन असली फोन नंबरों से टेस्टिंग करना बहुत उलझन भरा होता है: प्रोडक्शन डेटा का खतरा, टेस्ट अकाउंट की सफाई, अंतर्राष्ट्रीय नंबर की पहुँच — ये सारी परेशानियाँ डेवलपर के अनुभव को बिगाड़ देती हैं।

SMSCode API इन सभी समस्याओं का एक साफ-सुथरा हल पेश करता है। सुव्यवस्थित REST डिज़ाइन, एकसमान JSON जवाब, वेबहुक समर्थन, एक सौ से ज़्यादा देशों का कवरेज, पाँच सौ से अधिक सेवाओं का सपोर्ट — यह एक प्रोडक्शन-तैयार API है जो भारतीय डेवलपर के लिए विशेष रूप से उपयुक्त है।

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

TL;DR: SMSCode REST API से किसी भी अनुप्रयोग में वर्चुअल नंबर और OTP की सुविधा जोड़ें। Bearer टोकन प्रमाणीकरण, JSON जवाब, वेबहुक समर्थन। Python, JavaScript और PHP के उदाहरण शामिल हैं। API key के लिए साइन अप करें — टेस्टिंग के लिए स्टार्टर बैलेंस भी मिलता है।

SMSCode API क्यों चुनें?

डेवलपर टूल का मूल्यांकन करते समय कुछ अहम पहलुओं पर ध्यान देना ज़रूरी है। SMSCode कई मोर्चों पर प्रतिस्पर्धियों से आगे है।

तकनीकी फ़ायदे

आधुनिक REST डिज़ाइन:

• अनुमानित एंडपॉइंट संरचना — कोई भ्रम नहीं
• एकसमान JSON जवाब प्रारूप (सफलता और त्रुटि दोनों स्थितियों में)
• मानक HTTP स्टेटस कोड
• स्टेटलेस बनावट — क्षैतिज स्केलिंग के लिए उपयुक्त

उच्च विश्वसनीयता:

• 99.9% अपटाइम का लक्ष्य
• OTP डिलीवरी में 95% से ज़्यादा सफलता दर
• औसतन दस से पच्चीस सेकंड में OTP डिलीवरी
• स्वचालित ऑर्डर समाप्ति और रिफंड तंत्र

डेवलपर के अनुकूल:

• वेबहुक समर्थन — रियल-टाइम OTP पुश नोटिफिकेशन (पोलिंग की ज़रूरत नहीं)
• एकसमान त्रुटि कोड — पूर्वानुमानित एरर हैंडलिंग
• Python, JavaScript और PHP के लिए तैयार कोड उदाहरण
• एक सौ अनुरोध प्रति मिनट की दर सीमा — अधिकांश अनुप्रयोगों के लिए पर्याप्त

व्यावसायिक फ़ायदे

लागत दक्षता:

• इस्तेमाल के अनुसार भुगतान — कोई मासिक सदस्यता नहीं
• भारत के नंबर: $0.005 से $0.01 प्रति OTP
• अमेरिका के नंबर: $0.01 से $0.02 प्रति OTP
• पाँच सौ से ज़्यादा सेवाएँ एक ही जगह — कई प्रदाताओं की ज़रूरत नहीं

भारत-विशिष्ट सुविधाएँ:

• +91 नंबर: उच्च उपलब्धता, ताज़ा पूल रोटेशन
• भारतीय मंच: Zomato, Swiggy, Paytm, Flipkart — सभी कवर
• IDR में मूल्य निर्धारण — परिचित शर्तों में कीमतें

प्रतिस्पर्धी तुलना:

कारक	SMSCode	SMS-Activate	5sim
भारत के नंबर	उत्कृष्ट	अच्छा	सीमित
API डिज़ाइन	आधुनिक REST	पुराना REST	REST
वेबहुक	हाँ	सीमित	नहीं
कीमत	कम	बीस से पैंतीस प्रतिशत अधिक	तुलनीय
दस्तावेज़ीकरण	अच्छा	अच्छा	पर्याप्त
सफलता दर	95% से ज़्यादा	90% से ज़्यादा	88-92%

अगर आप पहली बार SMSCode के बारे में जानना चाहते हैं, तो वर्चुअल नंबर क्या होता है यह गाइड पहले पढ़ें।

API पहुँच का सेटअप

पहला चरण: अकाउंट बनाएँ

SMSCode.gg पर जाएँ और:

1. अपना ईमेल पता दर्ज करें
2. एक मज़बूत पासवर्ड बनाएँ
3. ईमेल वेरिफाई करें
4. डैशबोर्ड तक पहुँचें

SMSCode पर रजिस्ट्रेशन कैसे करें की विस्तृत गाइड भी ज़रूर पढ़ें — वहाँ हर कदम की तस्वीरों सहित जानकारी दी गई है।

दूसरा चरण: API टोकन बनाएँ

Dashboard → Account → API अनुभाग में जाएँ:

1. “Generate API Token” पर क्लिक करें
2. टोकन कॉपी करें (यह केवल एक बार दिखता है — इसे सुरक्षित जगह सेव करें!)
3. ज़रूरत पड़ने पर टोकन दोबारा बना सकते हैं

तीसरा चरण: टोकन को सुरक्षित तरीके से सेव करें

स्रोत कोड में टोकन कभी हार्डकोड न करें। यह एक गंभीर सुरक्षा जोखिम है।

# .env फ़ाइल में सेव करें
SMSCODE_API_TOKEN=your_token_here

# Python — पर्यावरण चर से लोड करें
import os
API_TOKEN = os.environ.get("SMSCODE_API_TOKEN")
if not API_TOKEN:
    raise ValueError("SMSCODE_API_TOKEN not set")

// Node.js — पर्यावरण चर से लोड करें
const API_TOKEN = process.env.SMSCODE_API_TOKEN;
if (!API_TOKEN) {
    throw new Error("SMSCODE_API_TOKEN environment variable required");
}

.gitignore में यह लाइनें ज़रूर जोड़ें:

.env
.env.local
.env.production

इससे आपका टोकन गलती से गिटहब पर अपलोड नहीं होगा।

API की बनावट

आधार URL

https://api.smscode.gg/v1

सभी एंडपॉइंट इसी बेस URL से शुरू होते हैं।

प्रमाणीकरण

Bearer टोकन प्रमाणीकरण — उद्योग का मानक तरीका:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

सभी API अनुरोधों में Authorization हेडर अनिवार्य है। बिना इसके सभी अनुरोध 401 त्रुटि देंगे।

जवाब का प्रारूप

SMSCode एक एकसमान JSON अनुबंध बनाए रखता है — चाहे सफलता हो या विफलता:

सफल जवाब:

{
  "success": true,
  "data": { ... }
}

त्रुटि जवाब:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "मानव-पठनीय विवरण"
  }
}

यह एकरूपता त्रुटि प्रबंधन को पूर्वानुमानित और आसान बनाती है।

मुख्य API एंडपॉइंट

GET /v1/catalog — सेवाएँ और कीमतें

उपलब्ध सेवाएँ, देश और वर्तमान कीमतें प्राप्त करें:

GET /v1/catalog
Authorization: Bearer YOUR_API_TOKEN

वैकल्पिक क्वेरी पैरामीटर:

GET /v1/catalog?country=in&service=whatsapp

जवाब:

{
  "success": true,
  "data": [
    {
      "service": "whatsapp",
      "service_name": "WhatsApp",
      "country": "India",
      "country_code": "in",
      "price": 1500,
      "currency": "IDR",
      "availability": "high"
    },
    {
      "service": "telegram",
      "service_name": "Telegram",
      "country": "Russia",
      "country_code": "ru",
      "price": 800,
      "currency": "IDR",
      "availability": "high"
    }
  ]
}

उपयोग सुझाव: Catalog एंडपॉइंट को कैश करें (तीस से साठ मिनट TTL) — कीमत रोज़ नहीं बदलती, लेकिन उपलब्धता हर घंटे बदल सकती है। इससे अनावश्यक API कॉल बचती हैं।

POST /v1/orders — वर्चुअल नंबर ऑर्डर

POST /v1/orders
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "service": "whatsapp",
  "country": "in"
}

अनुरोध के पैरामीटर:

• service (अनिवार्य): सेवा कोड — “whatsapp”, “telegram”, “google”, “facebook” आदि
• country (अनिवार्य): ISO देश कोड — “in” (भारत), “us” (अमेरिका), “ru” (रूस) आदि

जवाब:

{
  "success": true,
  "data": {
    "order_id": "ord_abc123xyz789",
    "phone": "+919876543210",
    "status": "pending",
    "expires_at": "2026-03-16T10:30:00Z",
    "created_at": "2026-03-16T10:10:00Z"
  }
}

phone फ़ील्ड में वर्चुअल नंबर मिलता है — इसे लक्षित मंच पर रजिस्ट्रेशन के लिए इस्तेमाल करें।

ज़रूरी बात: ऑर्डर बनते ही बैलेंस से राशि काट ली जाती है। अगर OTP नहीं आती तो ऑर्डर समाप्त होने पर स्वतः रिफंड मिल जाता है।

GET /v1/orders/{order_id} — OTP स्थिति जाँच

GET /v1/orders/ord_abc123xyz789
Authorization: Bearer YOUR_API_TOKEN

प्रतीक्षारत (OTP अभी नहीं मिली):

{
  "success": true,
  "data": {
    "order_id": "ord_abc123xyz789",
    "phone": "+919876543210",
    "status": "pending",
    "expires_at": "2026-03-16T10:30:00Z"
  }
}

पूरा (OTP मिल गई):

{
  "success": true,
  "data": {
    "order_id": "ord_abc123xyz789",
    "phone": "+919876543210",
    "status": "completed",
    "sms": "Your WhatsApp code: 847291. Don't share this code.",
    "code": "847291",
    "received_at": "2026-03-16T10:12:35Z"
  }
}

समाप्त (OTP नहीं मिली):

{
  "success": true,
  "data": {
    "order_id": "ord_abc123xyz789",
    "status": "expired",
    "refunded": true
  }
}

POST /v1/orders/{order_id}/cancel — ऑर्डर रद्द करें

अगर OTP की ज़रूरत नहीं रही तो ऑर्डर रद्द करें — तुरंत रिफंड मिलता है:

POST /v1/orders/ord_abc123xyz789/cancel
Authorization: Bearer YOUR_API_TOKEN

जवाब:

{
  "success": true,
  "data": {
    "order_id": "ord_abc123xyz789",
    "status": "cancelled",
    "refunded": true
  }
}

ऑर्डर कब रद्द करें:

• मंच ने नंबर अस्वीकार किया
• उपयोगकर्ता ने प्रक्रिया बीच में छोड़ दी
• गलत सेवा या देश का ऑर्डर हो गया
• समय-सीमा से पहले सफाई करनी हो

GET /v1/balance — अकाउंट बैलेंस

GET /v1/balance
Authorization: Bearer YOUR_API_TOKEN

जवाब:

{
  "success": true,
  "data": {
    "balance": 50000,
    "currency": "IDR",
    "balance_usd": 3.10
  }
}

निगरानी सुझाव: बैलेंस सीमा अलर्ट ज़रूर लगाएँ — स्वचालित कम-बैलेंस सूचना आपको प्रोडक्शन में रुकावट से बचाएगी। SMSCode में रिचार्ज कैसे करें — यह गाइड भी पढ़ें।

पूरे कोड उदाहरण

Python — प्रोडक्शन-तैयार लागूकरण

import os
import time
import requests
from typing import Optional, Dict, Any

class SMSCodeClient:
    BASE_URL = "https://api.smscode.gg/v1"

    def __init__(self, api_token: str):
        self.headers = {
            "Authorization": f"Bearer {api_token}",
            "Content-Type": "application/json"
        }

    def _request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
        """त्रुटि प्रबंधन के साथ API अनुरोध करें"""
        url = f"{self.BASE_URL}{endpoint}"
        response = requests.request(method, url, headers=self.headers, **kwargs)

        data = response.json()

        if not data.get("success"):
            error = data.get("error", {})
            raise Exception(f"API Error {error.get('code')}: {error.get('message')}")

        return data["data"]

    def get_catalog(self, country: Optional[str] = None, service: Optional[str] = None):
        """उपलब्ध सेवाएँ और कीमतें प्राप्त करें"""
        params = {}
        if country:
            params["country"] = country
        if service:
            params["service"] = service
        return self._request("GET", "/catalog", params=params)

    def create_order(self, service: str, country: str) -> Dict:
        """वर्चुअल नंबर ऑर्डर बनाएँ"""
        return self._request("POST", "/orders", json={
            "service": service,
            "country": country
        })

    def get_order(self, order_id: str) -> Dict:
        """ऑर्डर की स्थिति जाँचें"""
        return self._request("GET", f"/orders/{order_id}")

    def cancel_order(self, order_id: str) -> Dict:
        """ऑर्डर रद्द करें और रिफंड पाएँ"""
        return self._request("POST", f"/orders/{order_id}/cancel")

    def wait_for_otp(
        self,
        order_id: str,
        timeout_seconds: int = 240,
        poll_interval: int = 10
    ) -> Optional[str]:
        """समय-सीमा के साथ OTP के लिए पोल करें"""
        attempts = timeout_seconds // poll_interval

        for attempt in range(attempts):
            time.sleep(poll_interval)

            order = self.get_order(order_id)
            status = order["status"]

            if status == "completed":
                return order["code"]
            elif status in ("expired", "cancelled"):
                return None

            print(f"प्रयास {attempt + 1}: अभी प्रतीक्षारत...")

        # समय-सीमा — रिफंड के लिए रद्द करें
        self.cancel_order(order_id)
        return None


# इस्तेमाल का उदाहरण
def verify_whatsapp(client: SMSCodeClient):
    """पूरा WhatsApp वेरिफिकेशन प्रवाह"""
    print("WhatsApp India नंबर के लिए ऑर्डर बना रहे हैं...")
    order = client.create_order("whatsapp", "in")

    phone = order["phone"]
    order_id = order["order_id"]
    print(f"वर्चुअल नंबर: {phone}")

    # TODO: यह फोन नंबर WhatsApp रजिस्ट्रेशन में डालें
    # [यहाँ आपका WhatsApp रजिस्ट्रेशन ऑटोमेशन]

    print("OTP का इंतज़ार हो रहा है...")
    otp = client.wait_for_otp(order_id)

    if otp:
        print(f"OTP मिली: {otp}")
        # TODO: WhatsApp में OTP दर्ज करें
        return {"phone": phone, "otp": otp}
    else:
        print("समय-सीमा के भीतर OTP नहीं मिली")
        return None


# मुख्य प्रवेश बिंदु
api_token = os.environ.get("SMSCODE_API_TOKEN")
client = SMSCodeClient(api_token)
result = verify_whatsapp(client)

JavaScript / Node.js — Async/Await पैटर्न

const axios = require('axios');

class SMSCodeClient {
    constructor(apiToken) {
        this.baseUrl = 'https://api.smscode.gg/v1';
        this.headers = {
            'Authorization': `Bearer ${apiToken}`,
            'Content-Type': 'application/json'
        };
    }

    async _request(method, endpoint, options = {}) {
        const url = `${this.baseUrl}${endpoint}`;
        const response = await axios({
            method,
            url,
            headers: this.headers,
            ...options
        });

        const { data } = response;
        if (!data.success) {
            const { code, message } = data.error || {};
            throw new Error(`API Error ${code}: ${message}`);
        }

        return data.data;
    }

    async getCatalog({ country, service } = {}) {
        const params = {};
        if (country) params.country = country;
        if (service) params.service = service;
        return this._request('GET', '/catalog', { params });
    }

    async createOrder(service, country) {
        return this._request('POST', '/orders', {
            data: { service, country }
        });
    }

    async getOrder(orderId) {
        return this._request('GET', `/orders/${orderId}`);
    }

    async cancelOrder(orderId) {
        return this._request('POST', `/orders/${orderId}/cancel`);
    }

    async waitForOTP(orderId, { timeoutMs = 240000, pollIntervalMs = 10000 } = {}) {
        const deadline = Date.now() + timeoutMs;

        while (Date.now() < deadline) {
            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));

            const order = await this.getOrder(orderId);

            if (order.status === 'completed') return order.code;
            if (['expired', 'cancelled'].includes(order.status)) return null;
        }

        await this.cancelOrder(orderId);
        return null;
    }
}

// इस्तेमाल का उदाहरण
async function main() {
    const client = new SMSCodeClient(process.env.SMSCODE_API_TOKEN);

    const order = await client.createOrder('telegram', 'ru');
    console.log(`वर्चुअल नंबर: ${order.phone}`);

    const otp = await client.waitForOTP(order.order_id);
    if (otp) {
        console.log(`OTP: ${otp}`);
    } else {
        console.log('OTP नहीं मिली');
    }
}

main().catch(console.error);

PHP — सरल लागूकरण

<?php
class SMSCodeClient {
    private string $apiToken;
    private string $baseUrl = 'https://api.smscode.gg/v1';

    public function __construct(string $apiToken) {
        $this->apiToken = $apiToken;
    }

    private function request(string $method, string $endpoint, array $data = []): array {
        $ch = curl_init();
        $url = $this->baseUrl . $endpoint;

        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $this->apiToken,
                'Content-Type: application/json'
            ]
        ]);

        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            if (!empty($data)) {
                curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
            }
        }

        $response = json_decode(curl_exec($ch), true);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if (!$response['success']) {
            $error = $response['error'] ?? [];
            throw new RuntimeException(
                "API Error {$error['code']}: {$error['message']}"
            );
        }

        return $response['data'];
    }

    public function createOrder(string $service, string $country): array {
        return $this->request('POST', '/orders', compact('service', 'country'));
    }

    public function getOrder(string $orderId): array {
        return $this->request('GET', "/orders/{$orderId}");
    }

    public function cancelOrder(string $orderId): array {
        return $this->request('POST', "/orders/{$orderId}/cancel");
    }

    public function waitForOTP(string $orderId, int $timeoutSeconds = 240): ?string {
        $deadline = time() + $timeoutSeconds;

        while (time() < $deadline) {
            sleep(10);
            $order = $this->getOrder($orderId);

            if ($order['status'] === 'completed') return $order['code'];
            if (in_array($order['status'], ['expired', 'cancelled'])) return null;
        }

        $this->cancelOrder($orderId);
        return null;
    }
}

// इस्तेमाल का उदाहरण
$client = new SMSCodeClient(getenv('SMSCODE_API_TOKEN'));
$order = $client->createOrder('whatsapp', 'in');
echo "वर्चुअल नंबर: {$order['phone']}\n";

$otp = $client->waitForOTP($order['order_id']);
echo $otp ? "OTP: {$otp}\n" : "OTP नहीं मिली\n";

वेबहुक — प्रोडक्शन में अनुशंसित तरीका

पोलिंग की कमियाँ:

• नेटवर्क ओवरहेड — हर दस सेकंड पर अनुरोध
• विलंबित पकड़ — शून्य से दस सेकंड की अतिरिक्त प्रतीक्षा
• दर सीमा की खपत बढ़ती है
• अनावश्यक सर्वर लोड

वेबहुक के फ़ायदे:

• तुरंत OTP सूचना (मिलीसेकंड में)
• कोई पोलिंग ओवरहेड नहीं
• दर सीमाएँ सुरक्षित रहती हैं
• साफ-सुथरी संरचना

वेबहुक सेटअप

1. Dashboard → Settings → Webhooks पर जाएँ
2. HTTPS एंडपॉइंट URL दर्ज करें (सार्वजनिक और HTTPS अनिवार्य)
3. सेव करें

वेबहुक पेलोड

OTP आते ही POST अनुरोध भेजा जाता है:

{
  "event": "otp_received",
  "order_id": "ord_abc123xyz789",
  "phone": "+919876543210",
  "code": "847291",
  "sms": "Your WhatsApp code: 847291. Don't share this code.",
  "received_at": "2026-03-16T10:12:35.123Z"
}

वेबहुक हैंडलर (Express.js)

const express = require('express');
const app = express();
app.use(express.json());

// मेमोरी स्टोर (प्रोडक्शन में Redis इस्तेमाल करें)
const pendingOrders = new Map();

// प्रतीक्षारत ऑर्डर दर्ज करें
function waitForWebhookOTP(orderId) {
    return new Promise((resolve) => {
        pendingOrders.set(orderId, resolve);

        // पाँच मिनट बाद समय-सीमा
        setTimeout(() => {
            if (pendingOrders.has(orderId)) {
                pendingOrders.delete(orderId);
                resolve(null);
            }
        }, 300000);
    });
}

// वेबहुक एंडपॉइंट
app.post('/webhook/smscode', (req, res) => {
    const { event, order_id, code } = req.body;

    // तुरंत पुष्टि करें (ज़रूरी — SMSCode को इंतज़ार न कराएँ)
    res.status(200).json({ received: true });

    if (event === 'otp_received' && pendingOrders.has(order_id)) {
        const resolve = pendingOrders.get(order_id);
        pendingOrders.delete(order_id);
        resolve(code);
    }
});

// आपके प्रवाह में इस्तेमाल
async function getOTPWithWebhook(client, service, country) {
    const order = await client.createOrder(service, country);
    console.log(`नंबर: ${order.phone}`);

    // वेबहुक का इंतज़ार शुरू करें
    const otpPromise = waitForWebhookOTP(order.order_id);

    // TODO: लक्षित मंच पर फोन नंबर इस्तेमाल करें

    const otp = await otpPromise;
    return otp;
}

app.listen(3000, () => console.log('वेबहुक सर्वर तैयार'));

त्रुटि प्रबंधन — पूरी गाइड

त्रुटि कोड संदर्भ तालिका

कोड	HTTP	अर्थ	अनुशंसित कार्रवाई
INSUFFICIENT_BALANCE	402	बैलेंस कम है	उपयोगकर्ता को सूचित करें, रिचार्ज के लिए भेजें
SERVICE_UNAVAILABLE	503	सेवा अस्थायी रूप से बंद	एक्सपोनेंशियल बैकऑफ से पुनः प्रयास
ORDER_NOT_FOUND	404	अमान्य order_id	order_id की वैधता जाँचें
RATE_LIMIT_EXCEEDED	429	बहुत अधिक अनुरोध	बैकऑफ से पुनः प्रयास
INVALID_TOKEN	401	API टोकन अमान्य	टोकन जाँचें या दोबारा बनाएँ
COUNTRY_NOT_SUPPORTED	400	देश उपलब्ध नहीं	अलग देश आज़माएँ
SERVICE_NOT_SUPPORTED	400	सेवा उपलब्ध नहीं	कैटलॉग जाँचें
ORDER_ALREADY_CANCELLED	409	पहले से रद्द	कोई कार्रवाई ज़रूरी नहीं

एक्सपोनेंशियल बैकऑफ के साथ पुनः प्रयास तर्क

import time
import random

def api_request_with_retry(fn, max_retries=3, base_delay=1.0):
    """अस्थायी त्रुटियों के लिए एक्सपोनेंशियल बैकऑफ से पुनः प्रयास"""
    retryable_codes = {429, 500, 502, 503, 504}

    for attempt in range(max_retries):
        try:
            return fn()
        except Exception as e:
            if hasattr(e, 'status_code') and e.status_code not in retryable_codes:
                raise  # पुनः प्रयास न करने योग्य त्रुटि

            if attempt == max_retries - 1:
                raise  # अधिकतम पुनः प्रयास हो चुके

            # जिटर के साथ एक्सपोनेंशियल बैकऑफ
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"प्रयास {attempt + 1} विफल, {delay:.1f} सेकंड में पुनः प्रयास...")
            time.sleep(delay)

दर सीमाएँ

SMSCode API की दर सीमाएँ:

• एक सौ अनुरोध प्रति मिनट प्रति IP पता
• एक हज़ार अनुरोध प्रति घंटे प्रति API कुंजी

दर सीमा से बचने के सर्वोत्तम तरीके:

1. वेबहुक > पोलिंग (अनुरोधों की संख्या नाटकीय रूप से कम होती है)
2. Catalog जवाब कैश करें (तीस से साठ मिनट)
3. ऑर्डर स्थिति जाँच: कम से कम दस सेकंड का अंतराल
4. एक साथ कई ऑर्डर: Queue लागू करें

सुरक्षा की सर्वोत्तम प्रथाएँ

API इंटीग्रेशन में सुरक्षा से समझौता नहीं होना चाहिए। कुछ ज़रूरी बातें:

टोकन सुरक्षा:

• API टोकन हमेशा पर्यावरण चर में रखें, कोड में कभी नहीं
• .gitignore में .env फ़ाइलें जोड़ें
• नियमित अंतराल पर टोकन रोटेट करें
• अलग-अलग वातावरण के लिए अलग-अलग टोकन रखें

वेबहुक सत्यापन:

• प्रोडक्शन में वेबहुक पेलोड का हस्ताक्षर सत्यापित करें
• पुष्टि करें कि अनुरोध वास्तव में SMSCode से आया है
• Dashboard में वेबहुक सीक्रेट कॉन्फ़िगर करें
• X-SMSCode-Signature हेडर को हमेशा सत्यापित करें

नेटवर्क सुरक्षा:

• सभी API संचार HTTPS पर होना चाहिए
• वेबहुक एंडपॉइंट भी HTTPS पर हो
• IP व्हाइटलिस्टिंग उपलब्ध होने पर ज़रूर करें

वर्चुअल नंबर सुरक्षित है या नहीं — यह गाइड भी पढ़ें जो आपके उपयोगकर्ताओं की चिंताओं का जवाब देती है।

एकाधिक देशों और सेवाओं की रणनीति

SMSCode API का एक बड़ा फ़ायदा यह है कि एक ही इंटीग्रेशन से आप सौ से ज़्यादा देशों और पाँच सौ से ज़्यादा सेवाओं तक पहुँच सकते हैं। लेकिन इसका सही इस्तेमाल करने के लिए कुछ रणनीतियाँ अपनानी होती हैं।

देश की प्राथमिकता कैसे तय करें:

हर सेवा के लिए सभी देशों में नंबर समान रूप से उपलब्ध नहीं होते। उदाहरण के लिए, WhatsApp के लिए भारतीय नंबर बहुत सस्ते और आसानी से उपलब्ध हैं, जबकि Telegram के लिए रूसी नंबर अधिक विश्वसनीय हो सकते हैं। Catalog एंडपॉइंट से availability फ़ील्ड देखकर सबसे अच्छा विकल्प चुनें।

फॉलबैक रणनीति:

def order_with_fallback(client, service, preferred_countries):
    """पसंदीदा देशों की सूची से पहला उपलब्ध नंबर लें"""
    catalog = client.get_catalog(service=service)

    # उपलब्धता के अनुसार नक्शा बनाएँ
    available = {
        item['country_code']: item
        for item in catalog
        if item['availability'] in ('high', 'medium')
    }

    for country in preferred_countries:
        if country in available:
            return client.create_order(service, country)

    raise Exception(f"{service} के लिए कोई देश उपलब्ध नहीं")

# इस्तेमाल
order = order_with_fallback(
    client,
    "whatsapp",
    ["in", "ru", "us", "gb"]  # प्राथमिकता क्रम
)

बैलेंस की योजना बनाना:

प्रोडक्शन में बैलेंस खत्म होने से बड़ी परेशानी हो सकती है। एक स्वचालित निगरानी प्रणाली बनाएँ जो बैलेंस एक निश्चित सीमा से नीचे जाने पर ईमेल या SMS अलर्ट भेजे। /v1/balance एंडपॉइंट को हर घंटे जाँचें और टीम को समय पर सूचित करें।

परीक्षण और विकास का माहौल

API के साथ काम करते समय स्थानीय विकास और प्रोडक्शन वातावरण को अलग रखना ज़रूरी है।

पर्यावरण प्रबंधन:

# विकास (.env.development)
SMSCODE_API_TOKEN=dev_token_here
SMSCODE_LOG_LEVEL=debug

# उत्पादन (.env.production)
SMSCODE_API_TOKEN=prod_token_here
SMSCODE_LOG_LEVEL=error

एकीकरण परीक्षण — मॉक क्लाइंट:

असली API कॉल के बिना अपने कोड को परीक्षण करने के लिए API क्लाइंट को मॉक करें। इससे टेस्टिंग तेज़ होती है और बैलेंस भी नहीं खर्च होता:

from unittest.mock import MagicMock

def test_otp_flow():
    """मॉक API क्लाइंट से परीक्षण करें"""
    mock_client = MagicMock()

    # ऑर्डर बनाने का मॉक जवाब
    mock_client.create_order.return_value = {
        "order_id": "test_order_123",
        "phone": "+919999999999",
        "status": "pending"
    }

    # OTP का मॉक जवाब
    mock_client.wait_for_otp.return_value = "123456"

    result = verify_whatsapp(mock_client)
    assert result["otp"] == "123456"
    assert result["phone"] == "+919999999999"
    print("परीक्षण सफल!")

इस तरह के यूनिट टेस्ट से आप असली API कॉल किए बिना अपने लॉजिक को सत्यापित कर सकते हैं — जिससे विकास की गति बढ़ती है और टेस्टिंग की लागत कम रहती है।

प्रोडक्शन चेकलिस्ट

सुरक्षा:

• API टोकन पर्यावरण चर में (हार्डकोड नहीं)
• .gitignore में .env फ़ाइलें
• वेबहुक एंडपॉइंट HTTPS
• टोकन रोटेशन अनुसूची तय करें

विश्वसनीयता:

• अस्थायी त्रुटियों के लिए पुनः प्रयास तर्क
• समय-सीमा पर ऑर्डर रद्द (रिफंड के लिए)
• त्रुटि लॉगिंग (order_id + error_code + टाइमस्टैंप)
• बैलेंस निगरानी अलर्ट (कम बैलेंस सूचना)

प्रदर्शन:

• Catalog कैशिंग लागू करें
• पोलिंग के बजाय वेबहुक को प्राथमिकता दें
• एक साथ कई ऑर्डर की दर सीमित करें
• डेटाबेस में ऑर्डर स्थिति सेव करें

अवलोकनीयता:

• OTP डिलीवरी समय ट्रैक करें
• प्रति सेवा सफलता दर नज़र रखें
• विफल ऑर्डर के पैटर्न का विश्लेषण करें

वास्तविक उपयोग के मामले

उपयोग 1: उपयोगकर्ता रजिस्ट्रेशन टेस्टिंग

def create_test_accounts(client, service, country, count=10):
    """लोड टेस्टिंग के लिए कई टेस्ट अकाउंट बनाएँ"""
    accounts = []

    for i in range(count):
        order = client.create_order(service, country)
        otp = client.wait_for_otp(order["order_id"])

        if otp:
            accounts.append({
                "phone": order["phone"],
                "otp": otp
            })

        time.sleep(2)  # दर सीमा का ध्यान रखें

    return accounts

उपयोग 2: प्राइवेसी सेवा के रूप में

अपने उपयोगकर्ताओं को गोपनीयता सुरक्षा दें:

• उपयोगकर्ता किसी मंच के लिए वर्चुअल नंबर माँगता है
• आपका ऐप SMSCode API को कॉल करता है
• उपयोगकर्ता को वर्चुअल नंबर वापस मिलता है
• वेबहुक के ज़रिए OTP उपयोगकर्ता तक पहुँचाई जाती है

वर्चुअल नंबर खरीदने की गाइड में इस बारे में विस्तार से बताया गया है।

उपयोग 3: स्वचालित QA फ्रेमवर्क

def test_registration_flow(client, app_url, service):
    """शुरू से अंत तक रजिस्ट्रेशन टेस्ट"""
    # वर्चुअल नंबर पाएँ
    order = client.create_order(service, "in")
    phone = order["phone"]

    # अपने ऐप पर रजिस्ट्रेशन शुरू करें
    requests.post(f"{app_url}/register", json={"phone": phone})

    # OTP पाएँ
    otp = client.wait_for_otp(order["order_id"])
    assert otp, "OTP नहीं मिली"

    # वेरिफिकेशन पूरा करें
    response = requests.post(f"{app_url}/verify", json={
        "phone": phone, "otp": otp
    })
    assert response.json()["success"]
    print("रजिस्ट्रेशन प्रवाह सफलतापूर्वक पास हुआ")

SMSCode API का इस्तेमाल कैसे करें — इस विस्तृत गाइड में और भी उदाहरण मिलेंगे।

API इंटीग्रेशन में आम गलतियाँ

नए डेवलपर अक्सर कुछ गलतियाँ करते हैं जिनसे बचना ज़रूरी है:

गलती 1: बहुत ज़्यादा पोलिंग

हर एक सेकंड पर ऑर्डर स्थिति जाँचना दर सीमा को जल्दी खत्म करता है। कम से कम दस सेकंड का अंतराल रखें या वेबहुक इस्तेमाल करें।

गलती 2: ऑर्डर रद्द न करना

अगर उपयोगकर्ता प्रक्रिया बीच में छोड़ दे और आप ऑर्डर रद्द नहीं करते, तो बैलेंस बर्बाद होता है। हमेशा ऑर्डर रद्द करने का तंत्र रखें।

गलती 3: Catalog कैश न करना

हर ऑर्डर से पहले Catalog फिर से लोड करना अनावश्यक API कॉल करता है। Catalog को कम से कम तीस मिनट कैश करें।

गलती 4: एरर हैंडलिंग न करना

नेटवर्क त्रुटियाँ होती ही हैं। बिना एरर हैंडलिंग के प्रोडक्शन में अनुप्रयोग क्रैश हो सकता है। हमेशा try-catch और retry लॉजिक रखें।

गलती 5: एक ही टोकन सब जगह

डेवलपमेंट, स्टेजिंग और प्रोडक्शन के लिए अलग-अलग API टोकन बनाएँ। इससे सुरक्षा बेहतर रहती है और टेस्ट डेटा प्रोडक्शन को प्रभावित नहीं करता।

FAQ

SMSCode API की मुफ्त योजना है?

API पहुँच अकाउंट के साथ मुफ्त है। हर वर्चुअल नंबर ऑर्डर के लिए बैलेंस इस्तेमाल होता है — कोई मासिक सदस्यता नहीं है। मूल्य निर्धारण उपयोग-अनुसार-भुगतान मॉडल पर आधारित है: भारत के नंबर $0.005 से $0.01 प्रति OTP। टेस्टिंग के लिए $1 बैलेंस = पचास से दो सौ भारत OTP।

API से एक साथ कितने ऑर्डर दे सकते हैं?

मानक अकाउंट में पचास एक साथ सक्रिय ऑर्डर की सीमा है। उच्च-मात्रा की ज़रूरतों के लिए एंटरप्राइज़ योजना उपलब्ध है — समर्थन से संपर्क करें। दर सीमा: एक सौ अनुरोध प्रति मिनट प्रति IP।

वेबहुक हस्ताक्षर सत्यापन कैसे करें?

प्रोडक्शन में वेबहुक पेलोड का हस्ताक्षर ज़रूर सत्यापित करें — यह पुष्टि करता है कि अनुरोध वास्तव में SMSCode से आया है। Dashboard में वेबहुक सीक्रेट कॉन्फ़िगर करें और X-SMSCode-Signature हेडर को हर अनुरोध पर जाँचें।

OTP औसतन कितने सेकंड में आता है?

औसतन दस से पच्चीस सेकंड। Telegram सबसे तेज़ (पाँच से दस सेकंड), Google कुछ धीमा (पंद्रह से तीस सेकंड)। अधिकतम ऑर्डर वैधता बीस मिनट है। समाप्त ऑर्डर पर स्वतः रिफंड मिलता है।

क्या परीक्षण वातावरण उपलब्ध है?

अलग से कोई सैंडबॉक्स वातावरण नहीं है — प्रोडक्शन API पर ही टेस्टिंग होती है, लेकिन भारत के नंबर सबसे सस्ते ($0.005 से $0.01) होने की वजह से टेस्टिंग बहुत किफ़ायती है। $1 बैलेंस से व्यापक परीक्षण संभव है।

API टोकन खो जाए तो क्या करें?

Dashboard → Account → API अनुभाग में जाकर नया टोकन बना सकते हैं। पुराना टोकन तुरंत अमान्य हो जाता है। इसीलिए टोकन को सुरक्षित जगह सेव करना ज़रूरी है — वह केवल एक बार दिखता है।

किन सेवाओं के लिए वर्चुअल नंबर मिलते हैं?

पाँच सौ से ज़्यादा सेवाएँ कवर हैं — WhatsApp, Telegram, Google, Facebook, Instagram, Zomato, Swiggy, Paytm, Flipkart और सैकड़ों अन्य। वर्चुअल नंबर खरीदने की गाइड में पूरी सूची देखें।