Выберите язык

Быстрый старт с 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