Швидкий старт з API для розробників

API для розробників SmsGrab дає вашому ПЗ ті самі номери, що й застосунок, через REST API з форматом JSON. Це платний продукт із власними цінами для розробників, який оплачується зі звичайного балансу SmsGrab і захищений тими самими автоматичними поверненнями коштів.

Хто може користуватися

• Обліковий запис із підтвердженою адресою пошти. Гостьові облікові записи не можуть створювати ключі.
• Обліковий запис без обмежень.

1. Створіть API-ключ

Відкрийте Обліковий запис > Розробникам на сайті або Налаштування > API для розробників у застосунку й створіть ключ. Для безпеки підтвердьте дію паролем, а якщо ввімкнено двоетапну перевірку, то й її кодом. Виберіть область read для інструментів, які лише читають дані, або read і purchase, щоб купувати номери.

Ключ починається з sgk_ і показується лише один раз. Зберігайте його в сховищі секретів на сервері. Див. API-ключі та безпека.

2. Автентифікація

Базова URL-адреса: 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

Ключі мають зберігатися на серверах. Ніколи не вбудовуйте їх у сайт, розширення браузера чи застосунок, який ви роздаєте іншим людям.

3. Перевірте баланс і ціни

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

4. Купіть номер

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": [] }

5. Дочекайтеся SMS

Замість частого опитування в циклі дозвольте API утримувати запит до 30 секунд, поки щось не зміниться:

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

Надаєте перевагу push замість опитування? Налаштуйте вебхуки.

6. Завершіть або скасуйте

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 — поки ви ще чекаєте на перший код. Повна вартість повертається.
• Якщо нічого не робити, номер без коду завершиться через 20 хвилин, і кошти повернуться автоматично.

Значення статусу

Помилки

Усі помилки мають однакову структуру. Орієнтуйтеся на 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 (на одному обліковому записі одночасно можуть очікувати не більше 100 номерів) і 429 RATE_LIMITED із заголовком Retry-After.

Повний довідник — у документації для розробників.