مستندات API

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

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

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

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

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

محدودیت نرخ: به‌ازای هر کاربر (سهمیه مشترک بین همه کلیدهای API شما)، پنجره لغزان 60s. نقاط پایانی نوشتن (orders, cancel, next-sms) 10 req/min؛ نقاط پایانی خواندن (account, services, prices, list) 60 req/min. ساختن کلیدهای بیشتر سهمیه شما را افزایش نمی‌دهد.

موجودی فعلی و اطلاعات پایه پروفایل خود را دریافت کنید.

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"
}}

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

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 استفاده کنید.

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 پذیرفته می‌شوند.

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

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

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

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.

تا زمانی که 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 پس‌زمینه مشغول باشد، وضعیت را پیش می‌برد.

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

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 رد می‌شود.

پس از 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" }}

فهرست سفارش‌های اخیر شما با صفحه‌بندی مبتنی بر 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 صفحه قبل.

1. از طریق رابط وب شارژ کنید → GET /v1/account برای تأیید موجودی.
2. یک سرویس انتخاب کنید: GET /v1/services و GET /v1/prices?service=tg.
3. یک سفارش ایجاد کنید: POST /v1/orders با service + country.
4. مقدار data.phone را بخوانید و ارسال SMS از سرویس بالادست را از کلاینت خود تحریک کنید (مثلاً در ثبت‌نام Telegram جای‌گذاری کنید).
5. هر 3–5s GET /v1/orders/:id را استعلام کنید. وقتی status === "RECEIVED" شد، smsBody را بخوانید.
6. اگر SMS اشتباه بود یا کد دومی می‌خواهید: POST /v1/orders/:id/next-sms → بازگشت به WAITING.
7. تمام. اگر قبل از دریافت هر SMS لغو کنید: POST /v1/orders/:id/cancel برای بازپرداخت کامل.