API Documentation

Публичное REST API для покупки номеров и получения SMS. Доступ выдаётся по запросу — ключ можно сгенерировать в личном кабинете администратора в разделе «API».

Аутентификация

Все запросы должны содержать API ключ в заголовке Authorization:

Authorization: Bearer sms4g_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Альтернативно можно передать ключ в заголовке X-API-Key. Ключ никогда не передавайте в клиентском (браузерном) коде — только с вашего сервера.

Базовый URL

https://sms4g.store/api/v1

Эндпоинты

GET/auth

Проверка ключа

Проверяет, что ключ действителен, и возвращает данные аккаунта, к которому он привязан.

curl -H "Authorization: Bearer <key>" https://sms4g.store/api/v1/auth

Ответ 200:

{
  "success": true,
  "data": {
    "authenticated": true,
    "user": { "id": "cmxxx", "email": "admin@sms4g.store", "name": "Admin" }
  }
}

GET/balance

Баланс аккаунта

Возвращает текущий баланс на Sms4G, с которого списываются покупки номеров.

curl -H "Authorization: Bearer <key>" https://sms4g.store/api/v1/balance

Ответ 200:

{ "success": true, "data": { "balance": 42.50, "currency": "USD" } }

GET/numbers

Список своих номеров

Возвращает купленные номера с фильтрами. Все параметры query-string опциональны.

Параметр	Тип	Описание
geo	string	Код страны, напр. US, GB
date_from	ISO date	Куплен не раньше этой даты
date_to	ISO date	Куплен не позже этой даты
price_min	number	Минимальная цена покупки
price_max	number	Максимальная цена покупки
expires_after	ISO date	Истекает не раньше этой даты
expires_before	ISO date	Истекает не позже этой даты
limit / offset	number	Пагинация (limit по умолчанию 50, максимум 100)

curl -H "Authorization: Bearer <key>" \
  "https://sms4g.store/api/v1/numbers?geo=US&date_from=2026-08-01&price_max=2.5"

Ответ 200:

{
  "success": true,
  "data": {
    "numbers": [{
      "id": "cmabc123",
      "phone_number": "+15551234567",
      "country_code": "US",
      "provider": "SMS222",
      "number_type": "standard",
      "status": "active",
      "price": 1.5,
      "expires_at": "2026-09-20T00:00:00.000Z",
      "created_at": "2026-09-07T12:00:00.000Z",
      "link": "/sms/8f2c...публичный токен"
    }],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}

POST/numbers/buy

Купить номер

Покупает номер под указанное гео. Провайдер выбирается автоматически: сначала проверяются номера SMS222 (если есть в наличии), затем — обычные номера Risoffka. Если ничего не найдено — 404.

Поле	Тип	Описание
country_code	string, обязательно	Код страны, напр. US
price	number, опционально	Точная цена — купит номер только если его цена равна этому значению
price_min	number, опционально	Минимально допустимая цена (если price не задан)
price_max	number, опционально	Максимально допустимая цена (если price не задан)

curl -X POST -H "Authorization: Bearer <key>" -H "Content-Type: application/json" \
  -d '{"country_code":"US","price_max":2.0}' \
  https://sms4g.store/api/v1/numbers/buy

Ответ 201:

{
  "success": true,
  "data": {
    "id": "cmabc123",
    "phoneNumber": "+15551234567",
    "countryCode": "US",
    "provider": "SMS222",
    "numberType": "standard",
    "purchasePrice": "1.5000",
    "expiresAt": "2026-09-20T00:00:00.000Z"
  }
}

Номер закрепляется за вашим аккаунтом так же, как при покупке на сайте, и сумма списывается с баланса, возвращённого в /balance.

GET/numbers/:id/sms

Последнее SMS

Возвращает последнее полученное SMS на указанный номер (id из /numbers).

curl -H "Authorization: Bearer <key>" https://sms4g.store/api/v1/numbers/cmabc123/sms

Ответ 200:

{
  "success": true,
  "data": {
    "id": "sms_1",
    "from_number": "Google",
    "message_body": "G-123456 is your Google verification code",
    "code": "123456",
    "received_at": "2026-09-07T12:05:00.000Z"
  }
}

Если SMS ещё не пришло — 404 «SMS ещё не получено».

GET/numbers/:id/sms/all

Все SMS по номеру

Возвращает список всех SMS, полученных на номер, с пагинацией (limit/offset).

curl -H "Authorization: Bearer <key>" "https://sms4g.store/api/v1/numbers/cmabc123/sms/all?limit=50"

Ответ 200:

{
  "success": true,
  "data": {
    "messages": [
      { "id": "sms_2", "from_number": "Google", "message_body": "...", "code": "654321", "received_at": "..." },
      { "id": "sms_1", "from_number": "Google", "message_body": "...", "code": "123456", "received_at": "..." }
    ],
    "total": 2
  }
}

Ошибки

Все ошибки возвращаются в формате { "error": "..." } с соответствующим HTTP статус-кодом.

Код	Значение
400	Некорректные параметры запроса (validation)
401	Отсутствует или недействителен API ключ
402	Недостаточно средств на балансе
403	Доступ к API запрещён для этого аккаунта
404	Номер / SMS / подходящее предложение не найдено
409	Гонка при покупке — номер уже забрал кто-то другой, повторите запрос
429	Превышен лимит запросов (см. Rate limits ниже)
500 / 503	Внутренняя ошибка или временная недоступность провайдера номеров

Лимиты запросов

Эндпоинт	Лимит
/balance, /numbers, /numbers/:id/sms*	60 запросов в минуту на ключ
/numbers/buy	20 запросов в минуту на ключ

При превышении лимита ответ содержит заголовок Retry-After с числом секунд до разблокировки.

Безопасность

Ключ выдаётся только администраторам — доступ к API для обычных клиентов пока закрыт.
Никогда не передавайте ключ в клиентском коде (браузер, мобильное приложение) — только с бэкенда.
Если ключ скомпрометирован — перегенерируйте его в разделе «API» админ-панели, старый ключ сразу перестанет работать.
Все запросы должны выполняться по HTTPS.
Номера, купленные через API, принадлежат аккаунту, которому выдан ключ — так же, как при покупке на сайте.