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

Полный справочник — в документации для разработчиков.