شروع سریع API توسعه‌دهندگان

API توسعه‌دهندگان SmsGrab همان شماره‌های اپ را از طریق یک REST API با قالب JSON در اختیار نرم‌افزار شما می‌گذارد. این یک محصول پولی با قیمت‌های ویژه توسعه‌دهندگان است که از موجودی عادی SmsGrab پرداخت می‌شود و همان بازپرداخت‌های خودکار را دارد.

چه کسانی می‌توانند استفاده کنند

• حساب ایمیلی با نشانی تأییدشده. حساب‌های مهمان نمی‌توانند کلید بسازند.
• حسابی بدون محدودیت.

۱. کلید API بسازید

در وب‌سایت حساب > توسعه‌دهندگان یا در اپ تنظیمات > API توسعه‌دهندگان را باز کنید و یک کلید بسازید. برای امنیت، با گذرواژه و اگر تأیید دومرحله‌ای روشن است با کد آن تأیید می‌کنید. دامنه read را برای ابزارهای فقط‌خواندنی یا read و purchase را برای خرید شماره انتخاب کنید.

کلید با sgk_ شروع می‌شود و فقط یک بار نمایش داده می‌شود. آن را در مخزن اسرار سرورتان نگه دارید. ببینید: کلیدهای API و امنیت.

۲. احراز هویت

نشانی پایه https://smsgrab.com/api/dev/v1 است. کلید را به‌صورت توکن bearer یا در سرآیند X-Api-Key بفرستید:

GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here

جای کلیدها روی سرورهاست. هرگز آن‌ها را در وب‌سایت، افزونه مرورگر یا اپی که به دیگران می‌دهید قرار ندهید.

۳. موجودی و قیمت‌ها را ببینید

export SMSGRAB_KEY="sgk_your_key_here"

curl -s https://smsgrab.com/api/dev/v1/balance \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

مبالغ همیشه به کوچک‌ترین واحد USD هستند، پس 18 یعنی 0.18 USD. price_minor قیمت توسعه‌دهنده شما و retail_price_minor قیمت اپ است.

{ "currency": "USD", "markup_percent": 80,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 18,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

۴. شماره بخرید

curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
  -H "Authorization: Bearer $SMSGRAB_KEY" \
  -H "Idempotency-Key: order-7f3c2a" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp","country":"indonesia","max_price_minor":20}'

• service و country شناسه‌های ما را می‌پذیرند، مثل whatsapp و indonesia. برای کشورها کدهای ISO مثل ID هم پذیرفته می‌شود.
• max_price_minor از شما محافظت می‌کند: اگر قیمت بالا رفته باشد، چیزی کسر نمی‌شود و 409 PRICE_CHANGED می‌گیرید.
• Idempotency-Key تلاش دوباره را امن می‌کند. تکرار درخواست با همان کلید، به‌جای خرید دوباره، همان نتیجه اول را برمی‌گرداند.

پاسخ، 201 Created همراه با فعال‌سازی است:

{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
  "service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
  "price_minor": 18, "currency": "USD",
  "created_at": "2026-09-27T10:05:00.000Z", "expires_at": "2026-09-27T10:25:00.000Z",
  "refunded": false, "refund_minor": 0, "sms": [] }

۵. منتظر پیامک بمانید

به‌جای پرس‌وجو در یک حلقه تنگ، بگذارید API درخواست را تا ۳۰ ثانیه نگه دارد تا چیزی تغییر کند:

curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

وقتی پیامی برسد، status به CODE_RECEIVED تغییر می‌کند و sms همه پیام‌های تا آن لحظه را دارد:

{ "status": "CODE_RECEIVED",
  "sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
             "received_at": "2026-09-27T10:06:12.004Z" } ] }

ارسال فوری را به پرس‌وجو ترجیح می‌دهید؟ وب‌هوک‌ها را راه‌اندازی کنید.

۶. پایان یا لغو

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/finish \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/cancel \
  -H "Authorization: Bearer $SMSGRAB_KEY"

• finish بعد از استفاده از کد. فقط بعد از رسیدن کد پذیرفته می‌شود.
• cancel تا وقتی هنوز منتظر اولین کد هستید. کل مبلغ بازپرداخت می‌شود.
• اگر کاری نکنید، شماره بدون کد بعد از ۲۰ دقیقه منقضی و خودکار بازپرداخت می‌شود.

مقادیر وضعیت

خطاها

همه خطاها شکل یکسانی دارند. بر اساس code و reason عمل کنید و دلیل‌هایی را که هنوز نمی‌شناسید نادیده بگیرید:

{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }

موارد رایج عبارت‌اند از 402 INSUFFICIENT_BALANCE، 409 NO_NUMBERS_AVAILABLE، 409 PRICE_CHANGED، 422 با ACTIVATION_LIMIT_REACHED (در هر حساب حداکثر ۱۰۰ شماره می‌توانند هم‌زمان منتظر باشند) و 429 RATE_LIMITED با سرآیند Retry-After.

مرجع کامل در مستندات توسعه‌دهندگان است.