Виберіть мову

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

Купуйте номери й читайте коди зі свого ПЗ. Створіть ключ, дізнайтеся ціни, купіть номер, дочекайтеся SMS і завершіть, крок за кроком.

На цій сторінці
  1. Хто може користуватися
  2. 1. Створіть API-ключ
  3. 2. Автентифікація
  4. 3. Перевірте баланс і ціни
  5. 4. Купіть номер
  6. 5. Дочекайтеся SMS
  7. 6. Завершіть або скасуйте
  8. Значення статусу
  9. Помилки

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:

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

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

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

Bash
export SMSGRAB_KEY="sgk_your_key_here"

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

Суми завжди зазначено в мінімальних одиницях USD, тож 24 означає 0,24 USD. price_minor — ваша ціна з урахуванням гуртової знижки, а retail_price_minor — ціна за прайсом у застосунку.

JSON
{ "currency": "USD", "discount_percent": 5,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 24,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

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

Bash
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":24}'
  • service і country приймають наші ідентифікатори, наприклад whatsapp і indonesia. Для країн підходять і ISO-коди, наприклад ID.
  • max_price_minor захищає вас: якщо ціна зросла, нічого не буде списано, і ви отримаєте 409 PRICE_CHANGED.
  • Idempotency-Key робить повтори безпечними. Повторний запит із тим самим ключем поверне перший результат замість другої покупки.

Відповідь — 201 Created з активацією:

JSON
{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
  "service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
  "price_minor": 24, "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 секунд, поки щось не зміниться:

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

Коли надходить повідомлення, status змінюється на CODE_RECEIVED, а sms містить усі повідомлення на цей момент:

JSON
{ "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. Завершіть або скасуйте

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

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

Статус Значення
WAITING_SMS Куплено, очікує на перше повідомлення
CODE_RECEIVED Надійшло щонайменше одне повідомлення
COMPLETED Завершено вами або після закінчення часу після коду
CANCELLED Скасовано до коду, кошти повернуто
EXPIRED Код не надійшов до expires_at, кошти повернуто

Помилки

Усі помилки мають однакову структуру. Орієнтуйтеся на code і reason та ігноруйте причини, які вам поки невідомі:

JSON
{ "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.

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

Ця стаття була корисною?

Досі потрібна допомога?

Напишіть нам. Ми відповідаємо на кожне повідомлення, зазвичай протягом кількох годин.

Або напишіть на support@smsgrab.com