API दस्तावेज़
jiema.my तक बैच / स्वचालित पहुँच के लिए REST API। इसे SMS सत्यापन को अपनी सेवाओं में एकीकृत करने के लिए उपयोग करें। सभी endpoints JSON लौटाते हैं।
प्रमाणीकरण
हर अनुरोध में आपकी API key शामिल होनी चाहिए:
Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
वैकल्पिक हेडर रूप: X-API-Key: jm_xxx…
/account/api-keys पर keys बनाएँ और रद्द करें। प्रत्येक उपयोगकर्ता अधिकतम 10 सक्रिय keys रख सकता है। पूर्ण token केवल बनाते समय एक बार दिखाया जाता है — इसे सुरक्षित स्थान पर रखें।
त्रुटियाँ और रेट लिमिट
सभी त्रुटियाँ JSON लौटाती हैं:
{ "ok": false, "code": "RATE_LIMITED", "message": "..." }| HTTP | code | अर्थ |
|---|---|---|
| 401 | AUTH_MISSING / AUTH_INVALID | कोई key नहीं या रद्द की गई |
| 403 | FORBIDDEN | प्रतिबंधित या कोई पहुँच नहीं |
| 400 | BAD_REQUEST / INSUFFICIENT / NO_NUMBERS / … | मान्यता या व्यावसायिक त्रुटि |
| 404 | NOT_FOUND | ऑर्डर मौजूद नहीं है (या आपका नहीं है) |
| 429 | RATE_LIMITED | प्रति-key थ्रॉटलिंग |
| 500 | INTERNAL | सर्वर त्रुटि (स्वतः रिपोर्ट की गई) |
रेट लिमिट: प्रति key, स्लाइडिंग 60s विंडो। राइट endpoints (orders, cancel, next-sms) 10 req/min; रीड endpoints (account, services, prices, list) 60 req/min।
GET /v1/account
अपना वर्तमान बैलेंस और मूल प्रोफ़ाइल प्राप्त करें।
curl https://jiema.my/api/v1/account \
-H "Authorization: Bearer jm_xxx"
# 200 OK
{ "ok": true, "data": {
"id": "clxxxxxxxxxxx",
"balanceCents": "1200", // string to preserve precision; $12.00
"referralCode": "abc123",
"displayName": "Alice",
"lang": "en"
}}GET /v1/services
स्टॉक के साथ सेवाओं की सूची। सर्वर साइड पर ~5 मिनट कैश की जाती है।
curl https://jiema.my/api/v1/services -H "Authorization: Bearer jm_xxx"
{ "ok": true, "data": { "items": [
{ "code": "tg", "slug": "telegram", "name": "Telegram",
"minCostUsd": 0.18, "totalCount": 1234, "countryCount": 24 },
...
] }}ऑर्डर बनाते समय service फ़ील्ड के रूप में code (या मित्रवत slug) का उपयोग करें।
GET /v1/countries
curl https://jiema.my/api/v1/countries -H "Authorization: Bearer jm_xxx"
{ "ok": true, "data": { "items": [
{ "id": 7, "slug": "my", "name": "Malaysia" },
...
] }}id अपस्ट्रीम की संख्यात्मक देश id है; slug SEO शॉर्ट कोड है (जैसे "my" / "us")। country फ़ील्ड के रूप में दोनों रूप काम करते हैं।
GET /v1/prices?service=tg
किसी सेवा के लिए प्रति-देश मूल्य और स्टॉक। मूल्यों में पहले से ही ops द्वारा कॉन्फ़िगर की गई मार्कअप / छूट शामिल है।
curl "https://jiema.my/api/v1/prices?service=tg" -H "Authorization: Bearer jm_xxx"
{ "ok": true, "data": {
"service": "tg",
"items": [
{ "countryId": 7, "countrySlug": "my", "priceCents": "32", "count": 540 },
...
]
}}POST /v1/orders
एक SMS सत्यापन ऑर्डर बनाएँ। सिस्टम अपस्ट्रीम से एक फ़ोन नंबर आरक्षित करता है और आपके बैलेंस से शुल्क काटता है।
curl -X POST https://jiema.my/api/v1/orders \
-H "Authorization: Bearer jm_xxx" \
-H "content-type: application/json" \
-d '{ "service": "tg", "country": 7 }'
{ "ok": true, "data": {
"id": "ckxxxxx",
"status": "WAITING",
"service": "tg",
"country": "7",
"phone": "+60123456789",
"expiresAt": "2026-05-22T08:30:00.000Z",
"chargedCents": "32"
}}service / country के अलावा कोई वैकल्पिक फ़ील्ड नहीं।
सामान्य त्रुटि कोड: INSUFFICIENT (टॉप-अप आवश्यक), NO_NUMBERS, BAD_SERVICE, BAD_COUNTRY।
GET /v1/orders/:id
तब तक पोल करें जब तक status RECEIVED न हो जाए और smsBody खाली न रहे।
curl https://jiema.my/api/v1/orders/ckxxxxx -H "Authorization: Bearer jm_xxx"
{ "ok": true, "data": {
"id": "ckxxxxx",
"status": "RECEIVED",
"phone": "+60123456789",
"smsBody": "Your verification code is 123456",
"smsHistory": [
{ "body": "Your verification code is 123456", "receivedAt": "..." }
],
"smsReceivedAt": "2026-05-22T08:12:34.000Z",
...
}}स्थितियाँ: WAITING (नंबर सक्रिय, SMS की प्रतीक्षा) · RECEIVED (कोड आ गया) · COMPLETED / FAILED / CANCELLED अंतिम हैं।
सुझाई गई पोलिंग: हर 3–5 सेकंड। अपस्ट्रीम सिंक इसी endpoint के अंदर चलता है, इसलिए बैकग्राउंड worker व्यस्त होने पर भी आपकी पोलिंग स्थिति को आगे बढ़ाती है।
POST /v1/orders/:id/cancel
ऐसा ऑर्डर रद्द करें जिसे अभी तक कोड नहीं मिला है। आपके बैलेंस में पूर्ण रिफंड।
curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/cancel \
-H "Authorization: Bearer jm_xxx"
{ "ok": true, "data": { "id": "ckxxxxx", "status": "CANCELLED" }}यदि नंबर ने कोई SMS प्राप्त किया है तो CODE_RECEIVED के साथ अस्वीकृत, या यदि status समवर्ती रूप से बदला है तो ALREADY_CHANGED के साथ।
POST /v1/orders/:id/next-sms
RECEIVED के बाद, अपस्ट्रीम से नंबर सक्रिय रखने और दूसरे SMS की प्रतीक्षा करने के लिए कहें (सक्रिय विंडो के भीतर कोई अतिरिक्त शुल्क नहीं)।
curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/next-sms \
-H "Authorization: Bearer jm_xxx"
{ "ok": true, "data": { "id": "ckxxxxx", "status": "WAITING" }}GET /v1/orders
आपके हाल के ऑर्डर की cursor-पेजिनेटेड सूची।
curl "https://jiema.my/api/v1/orders?limit=20" -H "Authorization: Bearer jm_xxx"
{ "ok": true, "data": {
"items": [ { "id": "ck...", "status": "RECEIVED", "service": "tg", ... }, ... ],
"nextCursor": "ck..." | null
}}वैकल्पिक क्वेरी: status · limit 1–100 (डिफ़ॉल्ट 20) · cursor = पिछले पृष्ठ का nextCursor।
सामान्य वर्कफ़्लो
- वेब UI के माध्यम से टॉप अप करें → बैलेंस की पुष्टि के लिए GET /v1/account।
- एक सेवा चुनें: GET /v1/services और GET /v1/prices?service=tg।
- ऑर्डर बनाएँ: service + country के साथ POST /v1/orders।
- data.phone पढ़ें और अपने क्लाइंट से अपस्ट्रीम SMS ट्रिगर करें (जैसे Telegram रजिस्ट्रेशन में पेस्ट करें)।
- हर 3–5s पर GET /v1/orders/:id पोल करें। जब status === "RECEIVED" हो, smsBody पढ़ें।
- यदि गलत SMS है या दूसरा कोड चाहिए: POST /v1/orders/:id/next-sms → वापस WAITING पर।
- हो गया। यदि कोई SMS आने से पहले रद्द करते हैं: पूर्ण रिफंड के लिए POST /v1/orders/:id/cancel।