🔗 آدرس پایه (Base URL)

https://numax.ir/api/

تمام درخواست‌ها به صورت HTTPS GET ارسال می‌شوند.

🔑 احراز هویت (Authentication)

هر درخواست باید دارای پارامتر زیر باشد:

📌 نکته امنیتی:

• هر API Key یکتا بوده و به حساب کاربری و کیف پول خاصی متصل است.
• برای دریافت توکن یک درخواست پشتیبانی بفرستید تا توکن شما برایتان تولید و ارسال گردد.
• توصیه می‌شود کلید در محیط سرور نگهداری شود و در فایل‌های فرانت‌اند (JavaScript) استفاده نشود.
• در صورت مشاهده فعالیت مشکوک، فوراً API Key را از پنل خود غیرفعال کنید.

📲 متد ۱ — دریافت شماره جدید (Get Number)

آدرس:

https://numax.ir/api/?method=getnum&apikey=...&number_id=...

پارامترها:

پاسخ موفق:

{
  "status": "success",
  "number": "+1234567890",
  "order_id": 3812,
  "country": "United States",
  "service": "Telegram",
  "duration": "15:00",
  "price": 1.2,
  "hint": "Available for Telegram Verification"
}

کد خطاهای ممکن:

📩 متد ۲ — بررسی وضعیت پیامک (Get Status)

آدرس:

https://numax.ir/api/?method=getstatus&apikey=...&order_id=...

پارامترها:

پاسخ موفق:

{
  "status": "wait-code",
  "number": "+1234567890",
  "order_id": 3812,
  "country": "United States",
  "service": "Telegram",
  "duration": "00:15:00",
  "price": 1.2,
  "code": "12345"
}

توضیح وضعیت‌ها:

❌ متد ۳ — لغو شماره (Cancel Number)

آدرس:

https://numax.ir/api/?method=cancelnum&apikey=...&order_id=...

پارامترها:

پاسخ موفق:

{
  "status": "canceled",
  "number": "+1234567890",
  "order_id": 3812,
  "country": "United States",
  "service": "Telegram",
  "price": 1.2,
  "code": null
}

احتمال پاسخ‌های دیگر:

🌍 فهرست کشورها (Country List)

آدرس:

https://numax.ir/api/country-list&apikey=...

پاسخ:

[
  {
    "id": 1,
    "name": "United States",
    "flag": "🇺🇸",
    "slug": "us",
    "dialing_code": "+1"
  },
  ...
]

✅ پاسخ به‌صورت فشرده با gzip بازگردانده می‌شود.

🏷 فهرست سرویس‌ها (Service List)

آدرس:

https://numax.ir/api/service-list&apikey=...

پاسخ:

[
  {
    "id": 1,
    "name": "Telegram",
    "official_name": "Telegram",
    "icon": "https://cdn.numax.ir/icons/tg.svg",
    "slug": "telegram"
  },
  ...
]

✅ پاسخ‌ها فشرده (gzip) هستند تا حجم داده‌ها کاهش یابد.

📞 فهرست شماره‌ها (Number List)

آدرس:

https://numax.ir/api/number-list&apikey=...

پاسخ:

[
  {
    "id": 331,
    "country__name": "Russia",
    "service__name": "Telegram",
    "operator": "Beeline",
    "price": 0.9,
    "quantity": 120,
    "quality_calculated": 4.7,
    "time": "00:15:00",
    "description": "Fast SMS Code delivery."
  },
  ...
]

🧠 نکات امنیتی و فنی

1. استفاده از HTTPS اجباری است.
   تماس‌های ناامن HTTP مسدود شوند.

2. کلیدها در لاگ‌ها ذخیره نشوند.

3. محدودسازی درخواست‌ها (Rate-Limiting):

   • حداکثر ۵ درخواست در ثانیه برای هر IP توصیه می‌شود.
   • در صورت نقض، سیستم API موقتاً کاربر را مسدود می‌کند.

4. کدهای خطا را بررسی کنید:
   به‌جای اعتماد به متن، همیشه از فیلد status برای تشخیص موفقیت استفاده کنید.

5. درخواست‌ها در بک‌اند ارسال شوند.
   هرگز کلید API را در JavaScript فرانت‌اند یا برنامه موبایل ذخیره نکنید.

6. gzip Compression:
   پاسخ‌ها به‌صورت خودکار با GZIP فشرده می‌شوند برای کاهش مصرف پهنای باند.

💬 مثال کامل گردش کار

1. دریافت فهرست سرویس‌ها (service-list) و کشورها (country-list)
2. انتخاب شماره از number-list
3. ارسال درخواست getnum برای تهیه شماره
4. ذخیره order_id
5. بررسی مداوم با getstatus (تا زمان دریافت کد - حداقل هر 15 ثانیه بررسی شود.)
6. لغو در صورت نیاز با cancelnum