डेवलपर API की त्वरित शुरुआत

SmsGrab डेवलपर API आपके सॉफ़्टवेयर को वही नंबर देता है जो ऐप में हैं, JSON पर चलने वाले REST API के ज़रिए। यह एक सशुल्क प्रोडक्ट है जिसकी अपनी डेवलपर कीमतें हैं, आपके सामान्य SmsGrab बैलेंस से चुकाई जाती हैं और उसी अपने आप पैसा वापसी के दायरे में आती हैं।

कौन इस्तेमाल कर सकता है

• पुष्टि किए गए पते वाला ईमेल खाता। मेहमान खाते कुंजियाँ नहीं बना सकते।
• बिना प्रतिबंध वाला खाता।

1. API कुंजी बनाएँ

वेबसाइट पर खाता > डेवलपर या ऐप में सेटिंग्स > डेवलपर API खोलें और कुंजी बनाएँ। सुरक्षा के लिए आप अपने पासवर्ड से, और अगर दो-चरणीय सत्यापन चालू है तो उसके कोड से भी पुष्टि करते हैं। सिर्फ़ पढ़ने वाले टूल के लिए read स्कोप, या नंबर खरीदने के लिए read और purchase चुनें।

कुंजी sgk_ से शुरू होती है और सिर्फ़ एक बार दिखती है। इसे अपने सर्वर के सीक्रेट स्टोरेज में रखें। देखें API कुंजियाँ और सुरक्षा।

2. प्रमाणीकरण

बेस URL https://smsgrab.com/api/dev/v1 है। कुंजी bearer टोकन के रूप में या X-Api-Key हेडर में भेजें:

GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here

कुंजियों की जगह सर्वर पर है। इन्हें कभी वेबसाइट, ब्राउज़र एक्सटेंशन या दूसरों को दिए जाने वाले ऐप में न रखें।

3. अपना बैलेंस और कीमतें देखें

export SMSGRAB_KEY="sgk_your_key_here"

curl -s https://smsgrab.com/api/dev/v1/balance \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

रकम हमेशा USD की सबसे छोटी इकाइयों में होती है, इसलिए 18 का मतलब 0.18 USD है। price_minor आपकी डेवलपर कीमत है और retail_price_minor ऐप की कीमत।

{ "currency": "USD", "markup_percent": 80,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 18,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

4. नंबर खरीदें

curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
  -H "Authorization: Bearer $SMSGRAB_KEY" \
  -H "Idempotency-Key: order-7f3c2a" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp","country":"indonesia","max_price_minor":20}'

• service और country हमारे आईडी लेते हैं, जैसे whatsapp और indonesia। देशों के लिए ID जैसे ISO कोड भी चलते हैं।
• max_price_minor आपकी रक्षा करता है: अगर कीमत बढ़ गई है, तो कुछ नहीं कटता और आपको 409 PRICE_CHANGED मिलता है।
• Idempotency-Key दोबारा कोशिश को सुरक्षित बनाती है। उसी कुंजी से अनुरोध दोहराने पर दो बार खरीदने के बजाय पहला नतीजा लौटता है।

जवाब एक्टिवेशन के साथ 201 Created होता है:

{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
  "service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
  "price_minor": 18, "currency": "USD",
  "created_at": "2026-09-27T10:05:00.000Z", "expires_at": "2026-09-27T10:25:00.000Z",
  "refunded": false, "refund_minor": 0, "sms": [] }

5. SMS का इंतज़ार करें

तंग लूप में बार-बार पूछने के बजाय, API को कुछ बदलने तक अनुरोध 30 सेकंड तक रोके रखने दें:

curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

संदेश आने पर status बदलकर CODE_RECEIVED हो जाता है और sms में अब तक के सभी संदेश होते हैं:

{ "status": "CODE_RECEIVED",
  "sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
             "received_at": "2026-09-27T10:06:12.004Z" } ] }

बार-बार पूछने की जगह पुश चाहिए? वेबहुक सेट करें।

6. पूरा करें या रद्द करें

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/finish \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/cancel \
  -H "Authorization: Bearer $SMSGRAB_KEY"

• कोड इस्तेमाल करने के बाद finish। यह कोड आने के बाद ही स्वीकार होता है।
• पहले कोड का इंतज़ार करते समय cancel। पूरी कीमत लौट आती है।
• अगर आप कुछ नहीं करते, तो बिना कोड वाला नंबर 20 मिनट बाद खत्म हो जाता है और पैसा अपने आप लौट आता है।

स्थिति के मान

त्रुटियाँ

हर त्रुटि का आकार एक जैसा है। code और reason के आधार पर कदम उठाएँ, और जिन कारणों को आप अभी नहीं जानते उन्हें नज़रअंदाज़ करें:

{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }

आम स्थितियाँ हैं 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, ACTIVATION_LIMIT_REACHED के साथ 422 (हर खाते में एक साथ ज़्यादा से ज़्यादा 100 नंबर इंतज़ार कर सकते हैं) और Retry-After हेडर के साथ 429 RATE_LIMITED।

पूरा संदर्भ डेवलपर दस्तावेज़ में है।