SMS सत्यापन को ऑटोमेट करें: पूरी API गाइड

वेबसाइट कभी-कभार के साइनअप के लिए ठीक है: कुछ क्लिक करें, एक मैसेज का इंतज़ार करें। लेकिन जब आप स्वचालित टेस्ट लिख रहे हों, बल्क-साइनअप स्क्रिप्ट बना रहे हों, कोई CI पाइपलाइन चला रहे हों, या किसी बॉट को बिना किसी इंसानी मदद के वेरिफिकेशन कोड लेना हो, तब यह काम नहीं आती। वेबसाइट यह नहीं कर सकती। API कर सकता है। यह लेख शून्य से एक काम करते फ़्लो तक पहुँचने के लिए ज़रूरी हर चीज़ बताता है।

चरण 1: API key लें

/account/api-keys पर जाकर लॉग इन करें और एक key बनाएँ। Key, jm_ के बाद एक रैंडम स्ट्रिंग जैसी दिखती है। प्लेनटेक्स्ट सिर्फ़ एक बार दिखाया जाता है — हम key का hash स्टोर करते हैं, key खुद नहीं, इसलिए खो जाने पर “अपनी key वापस पाएँ” जैसा कोई विकल्प नहीं होता। उसे डिलीट करें और नई बना लें।

हर रिक्वेस्ट स्टैंडर्ड Bearer authentication इस्तेमाल करती है:

Authorization: Bearer jm_your_key

key को पासवर्ड जैसा ही समझें — इसे किसी पब्लिक repo में commit न करें, किसी को डीबग करने में मदद के लिए चैट में पेस्ट न करें। अगर लगे कि यह लीक हो गई है, तो /account/api-keys पर वापस जाएँ, उसे डिलीट करें, और नई जारी करें; पुरानी key उसी पल काम करना बंद कर देती है।

चरण 2: सर्विस और देश चुनें

ऑर्डर देने के लिए दो चीज़ों की ज़रूरत होती है: service (सर्विस कोड) और country (देश की id)। पहले कैटलॉग लिस्ट करके शुरू करें:

curl https://jiema.my/api/v1/services \
  -H "Authorization: Bearer jm_your_key"

हर आइटम में एक code फ़ील्ड होती है (Telegram के लिए tg) — इसे सीधे ऑर्डर endpoint को दें, खुद से slug बनाने की कोशिश करने से यह ज़्यादा भरोसेमंद है। किसी खास सर्विस की सभी देशों में लाइव कीमत और स्टॉक देखने के लिए, service पैरामीटर जोड़ें:

curl "https://jiema.my/api/v1/prices?service=tg" \
  -H "Authorization: Bearer jm_your_key"

items के हर एंट्री में countryId / priceCents / count (अभी उपलब्ध नंबरों की संख्या) होती है। ऑर्डर देने से पहले count देख लें — शून्य होने का मतलब है ऑर्डर फेल होगा, तो इसे मुश्किल तरीके से जानने में एक कॉल बर्बाद न करें।

चरण 3: ऑर्डर दें

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"6"}'

सफल ऑर्डर पर एक फ़ोन नंबर और एक्सपायरी टाइम मिलता है:

{
  "ok": true,
  "data": {
    "id": "cm...",
    "status": "WAITING",
    "phone": "62812xxxxxxx",
    "expiresAt": "2026-08-01T12:15:00.000Z",
    "chargedCents": "40"
  }
}

चार्ज इसी स्टेप पर लगता है — chargedCents वही रकम है जो असल में कटी (सेंट में)। यह नंबर टारगेट ऐप को वेरिफिकेशन कोड पाने के लिए दें, फिर अगले स्टेप पर जाएँ।

चरण 4: कोड के लिए पोल करें

कोई WebSocket या webhook push नहीं है — SMS का कंटेंट पाने के लिए GET /api/v1/orders/:id को तब तक पोल करते रहें जब तक smsBody, null न रह जाए:

while true; do
  RESP=$(curl -s https://jiema.my/api/v1/orders/$ORDER_ID \
    -H "Authorization: Bearer jm_your_key")
  BODY=$(echo "$RESP" | jq -r '.data.smsBody')
  if [ "$BODY" != "null" ]; then
    echo "Code received: $BODY"
    break
  fi
  sleep 5
done

पाँच सेकंड एक ठीकठाक शुरुआती बिंदु है — नंबर 15 मिनट तक वैध रहता है, और 60-रिक्वेस्ट-प्रति-मिनट की क्वेरी रेट लिमिट काफ़ी गुंजाइश छोड़ती है। अगर बेसब्री है तो तीन सेकंड भी ठीक है; हर सेकंड पोल करने से कोड जल्दी नहीं आता, इससे सिर्फ़ आपकी रेट लिमिट जल्दी खर्च होती है।

ध्यान रखने वाली बातें

• रेट लिमिट हर यूज़र पर लगती है, हर key पर नहीं। राइट endpoints (order / cancel / next-sms) पर हर यूज़र के लिए 10/मिनट की सीमा है; queries पर 60/मिनट। ज़्यादा key बनाने से ऊँची सीमा नहीं मिलती — सभी एक ही सीमा शेयर करती हैं।
• नंबर 15 मिनट बाद एक्सपायर हो जाते हैं। कोई अनयूज़्ड नंबर जो कोड मिलने से पहले एक्सपायर हो जाए, अपने-आप रिफ़ंड हो जाता है — माँगने की ज़रूरत नहीं। लेकिन अगर आपका अपना पाइपलाइन असल इस्तेमाल से पहले नंबर को बहुत देर तक रोक रखे (जैसे किसी क्यू में फँसा हो), तो आप तक पहुँचने तक वह मर चुका होगा।
• एक नंबर एक से ज़्यादा कोड पा सकता है। अगर टारगेट ऐप SMS दो चरणों में भेजता है (पहले साइनअप कन्फ़र्मेशन, फिर अलग लॉगिन कोड), पहला आने के बाद POST /api/v1/orders/:id/next-sms कॉल करके हमें बताएँ “यह वाला हो गया, सुनना जारी रखो” — नए नंबर के लिए नया ऑर्डर देने की ज़रूरत नहीं।
• कोड मिलने के बाद cancel काम नहीं करता। जब तक नंबर अभी भी कोड का इंतज़ार कर रहा है, POST /api/v1/orders/:id/cancel तुरंत रिफ़ंड कर देता है। एक बार smsBody कभी non-null हो जाए, तो वही कॉल इसके बदले CODE_RECEIVED एरर देता है — जो पैसा दिया था वह चीज़ मिल गई, तो अब पीछे जाने का कोई रास्ता नहीं।
• सिर्फ़ एक बार status चेक करके मत छोड़ें। status, WAITING से RECEIVED में बदलता है। अगर यह एक्सपायरी तक WAITING पर ही टिका रहे, तो आम तौर पर यह उस खास देश/सर्विस कॉम्बिनेशन की डिलीवरी-रेट की समस्या होती है — किसी दूसरे देश में नया ऑर्डर देना इंतज़ार करने से जल्दी नतीजा देता है।

अगले कदम

इससे ऑर्डर से कोड तक का मुख्य फ़्लो कवर हो जाता है। हर endpoint की पूरी फ़ील्ड लिस्ट, एरर कोड, और एज केस /api-docs पर मौजूद हैं। अगर आप इसे बड़े स्केल पर चला रहे हैं — जैसे दर्जनों अकाउंट्स के वेरिफिकेशन फ़्लो एक साथ ज़िंदा रखना — तो हर ऑर्डर के पोलिंग लूप को अलग-अलग समय दें। इन्हें एक ही सीक्वेंशियल लूप में लाइन में मत लगाएँ, वरना जब तक आप पहले का इंतज़ार कर रहे होंगे, पुराने नंबर एक्सपायर हो जाएँगे।