API для приёма СМС

API для приёма СМС — это три вызова: купить номер, дождаться кода, освободить номер. Он достаёт до 517 сервисов в 225 странах, номера начинаются от 0,07 €, а активация, на которую ничего не пришло, возвращается без обращения в поддержку. У ключей есть scope, покупки идемпотентны, а старые клиенты handler_api работают без изменений.

Открыть справочник разработчика Начать с €30

API одним блоком

Обновлено 28 авг. 2026 г.

Базовый URL: https://virtualsmsnumbers.com/api/v1
Аутентификация: Bearer-ключ или X-Api-Key
Лимит запросов: 120/мин, всплеск 20/с
Окно идемпотентности: 24 часа
Автовозврат через: 20 минут
Самая дешёвая активация: 0,07 €
Стран охвачено: 225
Формат: JSON, центы, ISO 8601 UTC

Цены и наличие берутся из операторского пула в его текущем состоянии, а не из опубликованного прайс-листа.

Поток из трёх вызовов

Всё остальное в справочнике необязательно. Это весь путь верификации, и он не менялся с 2019 года.

1
POST /activations
Запросите сервис и, если вам важно, страну. В ответе придут номер, цена в центах и время истечения. Передайте Idempotency-Key, чтобы повторённый запрос не купил второй номер, и max_price_cents, если вызывающая сторона автоматическая.
2
GET /activations/{id}?wait=180
Долгий опрос. Соединение держится открытым, пока не придёт сообщение или не истечёт таймаут, поэтому один запрос заменяет цикл, который сделал бы девяносто. Статус возвращается как code_received: разобранный код и рядом сырой текст, потому что отправители форматируют его по-разному.
3
POST /activations/{id}/complete
Закройте активацию и освободите линию. Если ничего не пришло, не делайте вообще ничего: окно истечёт само, а баланс вернётся. Досрочная отмена — тот же вызов под другим именем.

Рабочий пример

Задайте VSN_KEY и запустите. Ответы в комментариях — настоящие формы, включая поля, которые вы захотите сохранить.

buy-and-wait.sh

# 1. Buy a Telegram number in Portugal
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations \
  -H "Authorization: Bearer $VSN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"service":"telegram","country":"PT"}'

# {"id":"1043872915","phone_number":"351926114508","status":"waiting",
#  "price_cents":11,"expires_at":"2026-08-26T12:41:07Z"}

# 2. Long-poll until the code lands (blocks up to 120 s)
-kw">curl "https://virtualsmsnumbers.com/api/v1/activations/1043872915?wait=120" \
  -H "Authorization: Bearer $VSN_KEY"

# {"id":"1043872915","status":"code_received",
#  "messages":[{"code":"48219","text":"Telegram code: 48219"}]}

# 3. Release the number
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations/1043872915/complete \
  -H "Authorization: Bearer $VSN_KEY"

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

120 запросов в минуту на ключ, всплеск до 20 в секунду. В каждом ответе приходят X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset, а 429 говорит, сколько ждать, вместо того чтобы заставлять вас гадать.

Лимит редко становится ограничением, если API используют по назначению: один долгий опрос вместо девяноста, вебхук вместо таймера и списки стран и сервисов, закэшированные при старте. Если запас действительно нужен — попросите: поднять лимит проще для нас обоих, чем отлаживать парк ключей.

Идемпотентность

Передавайте заголовок Idempotency-Key в POST /activations. Повтор с тем же ключом в течение 24 часов вернёт исходную активацию в её текущем состоянии, с заголовком Idempotent-Replay, вместо покупки второго номера и второго списания.

Ключ не является хешем тела: другой payload под уже использованным ключом всё равно вернёт первую активацию. Генерируйте по одному ключу на логическую покупку — UUID вполне подойдёт — и переиспользуйте его между повторами, но никогда между покупками.

Старые клиенты handler_api

Скрипты, написанные под классический протокол handler_api.php, продолжают работать. Направьте их на совместимый эндпоинт, замените api_key — и те же действия вернут те же токены ACCESS_ и STATUS_, что и всегда.

Это слой перевода над тем же пулом, так что цены, остатки и возвраты ведут себя одинаково в обоих случаях. Новый код всё же стоит писать на /api/v1: в JSON-ответах есть метки времени, коды ошибок и поля цен, для которых в токенах места нет.

legacy-compat.sh

# Existing scripts keep working: same actions, same response tokens.
BASE="https://virtualsmsnumbers.com/stubs/handler_api.php"

-kw">curl "$BASE?api_key=$KEY&action=getNumber&service=tg&country=117"
# ACCESS_NUMBER:1043872915:351926114508

-kw">curl "$BASE?api_key=$KEY&action=getStatus&id=1043872915"
# STATUS_WAIT_CODE
# STATUS_OK:48219

-kw">curl "$BASE?api_key=$KEY&action=setStatus&id=1043872915&status=6"
# ACCESS_ACTIVATION

-kw">curl "$BASE?api_key=$KEY&action=getBalance"
# ACCESS_BALANCE:41.87

Агенты, MCP и обнаружение

Есть размещённый MCP-сервер, документ OpenAPI 3.1 и индекс llms.txt, так что агент найдёт нужные ему три инструмента без написанной вручную обвязки. Направьте клиент на эндпоинт ниже, и он обнаружит покупку, ожидание и освобождение.

Прежде чем позволить чему-то автономному тратить баланс: ограничьте ключ до scope numbers:read и numbers:write, задайте потолок max_price_cents на каждую покупку и выдайте ему отдельный ключ, чтобы его отзыв не уронил вашу боевую интеграцию.

Схема OpenAPI 3.1 Индекс llms.txt

mcp.json

{
  "mcpServers": {
    "virtualsmsnumbers": {
      "type": "http",
      "url": "https://virtualsmsnumbers.com/api/mcp",
      "headers": { "Authorization": "Bearer vsn_live_xxxxxxxxxxxx" }
    }
  }
}

Перед продакшеном

Задавайте max_price_cents на каждую покупку. Цены двигаются вместе с пулом, и неограниченный агент с удовольствием купит его дорогой конец.
Считайте идентификаторы непрозрачными строками. Идентификаторы активаций сегодня десятизначные; это не обещание, как и их длина.
Ветвитесь по коду ошибки, а не по тексту. Коды стабильны в пределах версии; тексты написаны для людей и переписываются.
Подпишитесь на sms.received и проверяйте подпись — HMAC-SHA256 по сырому телу, с окном повтора в пять минут — вместо опроса состояния, о котором вам могут сообщить сами.
Считайте арифметику по целочисленным полям в центах. Отформатированные строки рядом с ними нужны для отображения и зависят от локали.

Полный справочник

Шесть эндпоинтов, таблицы ошибок, полезные нагрузки вебхуков, scope и карта старых токенов.

Открыть справочник разработчика

Принять СМС онлайн Временный номер телефона Актуальные цены

Частые вопросы

Медианная доставка — меньше девяти секунд с момента отправки сервисом. Долгий опрос существует потому, что хвост длинный: активация остаётся открытой 20 минут и истекает в возврат, если ничего не пришло.

Ничего, что нужно обрабатывать. Окно закроется, баланс вернётся автоматически, а активация закончится в состоянии expired, которое можно прочитать через API.

Да, и это ничего не стоит. У ключей фиксированные scope, необязательный список разрешённых IP и срок действия, выбираемый при создании, так что утёкший ключ стенда не купит номера в проде.

Есть тонкие обёртки без зависимостей, но API — это шесть эндпоинтов поверх JSON: для потока из трёх вызовов честно хватает fetch, requests или curl.

В рамках одной активации — да: дополнительные сообщения приходят на тот же номер, пока она открыта. Между сессиями нужна аренда, которая держит линию от четырёх часов до двенадцати месяцев.

Нет. Это тот же пул по тем же ценам; отличается только кодировка ответов.