API разработчика

REST API позволяет управлять номерами программно: покупать активации и аренду, отслеживать статусы и получать SMS-коды.

Авторизация

Создайте API-ключ в личном кабинете и передавайте его в заголовке Authorization: Bearer <ключ>. Лимит — 60 запросов в минуту на ключ.

curl -H "Authorization: Bearer ss_live_xxxxxxxxxxxxxxxx" \
  https://your-domain.ru/api/v1/balance

Эндпоинты

Метод	Путь	Описание
GET	/api/v1/balance	Баланс аккаунта
GET	/api/v1/countries	Список доступных стран
GET	/api/v1/services	Список сервисов
GET	/api/v1/prices?country=RU	Цены по стране (все — без параметра)
POST	/api/v1/activations/buy	Купить разовую активацию {country, service}
GET	/api/v1/activations/{id}	Статус активации, код из SMS
POST	/api/v1/activations/{id}/cancel	Отменить и вернуть средства
POST	/api/v1/activations/{id}/complete	Подтвердить получение SMS
POST	/api/v1/rentals/buy	Арендовать номер {country, hours}
GET	/api/v1/rentals/{id}	Статус аренды
GET	/api/v1/rentals/{id}/sms	Входящие SMS аренды
POST	/api/v1/rentals/{id}/extend	Продлить аренду {hours}
POST	/api/v1/rentals/{id}/cancel	Отменить аренду (до первого SMS)

Пример запроса

1. Купить номер — POST /api/v1/activations/buy:

curl -X POST https://your-domain.ru/api/v1/activations/buy \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "RU", "service": "telegram"}'

Ответ:

{
  "ok": true,
  "data": {
    "id": "clx9f3k2...",
    "phone": "+79317024581",
    "status": "waiting",
    "price": 1490,
    "expiresAt": "2026-09-24T13:20:11.000Z"
  }
}

2. Ожидание SMS — GET /api/v1/activations/{id}:

curl -H "Authorization: Bearer $KEY" \
  https://your-domain.ru/api/v1/activations/clx9f3k2...

{ "ok": true, "data": { "status": "received", "code": "4821", ... } }

Коды ошибок

HTTP	Code	Описание
401	NO_AUTH / BAD_KEY	Ключ не передан или отозван
402	INSUFFICIENT_FUNDS	Недостаточно средств на балансе
404	NOT_FOUND	Объект не найден или чужой
409	NO_STOCK / BAD_STATUS	Нет номеров или недопустимый статус
422	BAD_INPUT	Некорректное тело запроса
429	RATE_LIMITED	Превышен лимит 60 запросов/мин