مستندات API

REST API برای دسترسی انبوه / خودکار به jiema.my. از آن برای ادغام تأیید پیامکی در سرویس‌های خود استفاده کنید. تمام نقاط پایانی JSON برمی‌گردانند.

برای ساخت اولین کلید API ورود کنید.

فهرست مطالب

احراز هویت
خطاها و محدودیت نرخ
GET /v1/account
GET /v1/services
GET /v1/countries
GET /v1/prices
POST /v1/orders
GET /v1/orders/:id
POST /v1/orders/:id/cancel
POST /v1/orders/:id/next-sms
GET /v1/orders
گردش کار معمول

احراز هویت

هر درخواست باید کلید API شما را شامل شود:

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

فرم هدر جایگزین: X-API-Key: jm_xxx…

کلیدها را در /account/api-keys بسازید و باطل کنید. هر کاربر می‌تواند حداکثر 10 کلید فعال داشته باشد. token کامل فقط یک بار هنگام ساخت نمایش داده می‌شود — آن را در جای امن ذخیره کنید.

خطاها و محدودیت نرخ

همه خطاها JSON برمی‌گردانند:

{ "ok": false, "code": "RATE_LIMITED", "message": "..." }

HTTP	code	معنا
401	AUTH_MISSING / AUTH_INVALID	بدون کلید یا کلید باطل‌شده
403	FORBIDDEN	مسدود یا بدون دسترسی
400	BAD_REQUEST / INSUFFICIENT / NO_NUMBERS / …	خطای اعتبارسنجی یا منطق کسب‌وکار
404	NOT_FOUND	سفارش وجود ندارد (یا متعلق به شما نیست)
429	RATE_LIMITED	محدودسازی نرخ به‌ازای هر کلید
500	INTERNAL	خطای سرور (به‌طور خودکار گزارش می‌شود)

محدودیت نرخ: به‌ازای هر کلید، پنجره لغزان 60s. نقاط پایانی نوشتن (orders, cancel, next-sms) 10 req/min؛ نقاط پایانی خواندن (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

فهرست سرویس‌ها همراه با موجودی. در سمت سرور حدود ۵ دقیقه کش می‌شود.

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 },
  ...
] }}

هنگام ایجاد سفارش، از code (یا slug خوانا) به‌عنوان فیلد service استفاده کنید.

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 شناسه عددی کشور در سرویس بالادست است؛ slug کد کوتاه برای SEO است (مثل "my" / "us"). هر دو فرم به‌عنوان فیلد country پذیرفته می‌شوند.

GET /v1/prices?service=tg

قیمت و موجودی هر کشور برای سرویس مشخص. قیمت‌ها قبلاً شامل افزایش / تخفیف پیکربندی‌شده توسط تیم عملیات هستند.

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

یک سفارش تأیید پیامکی بسازید. سیستم یک شماره از سرویس بالادست رزرو می‌کند و مبلغ را از موجودی شما کسر می‌کند.

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 ثانیه. همگام‌سازی با سرویس بالادست داخل همین نقطه پایانی اجرا می‌شود، بنابراین استعلام شما حتی اگر 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، و اگر وضعیت به‌طور هم‌زمان تغییر کرده باشد با 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 صفحه قبل.

گردش کار معمول

از طریق رابط وب شارژ کنید → GET /v1/account برای تأیید موجودی.
یک سرویس انتخاب کنید: GET /v1/services و GET /v1/prices?service=tg.
یک سفارش ایجاد کنید: POST /v1/orders با service + country.
مقدار 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 برای بازپرداخت کامل.

jiema.my