API для приёма SMS на виртуальные номера

Быстрый старт за 3 шага

Сначала зарегистрируйтесь бесплатно, пополните баланс и получите API-ключ в разделе API своего профиля. В примерах вместо YOUR_KEY подставьте свой ключ. Запросы могут быть GET или POST: при POST все параметры, включая api_key, можно передавать полями формы (application/x-www-form-urlencoded) в теле запроса, чтобы ключ не попадал в URL и журналы сервера. Два базовых адреса равнозначны: https://turonay.com/stubs/handler_api.php и https://turonay.com/api/.

1. Проверьте баланс

getBalance возвращает баланс в виде ACCESS_BALANCE:сумма; так же быстро проверяется, что ключ работает. Сумма указана в TRY и показывает доступный остаток за вычетом средств, зарезервированных под открытые активации.

curl "https://turonay.com/stubs/handler_api.php?api_key=YOUR_KEY&action=getBalance"
ACCESS_BALANCE:125.4000

2. Получите номер

service — код сервиса (wa для WhatsApp), country — идентификатор страны. Успешный запрос вернёт ACCESS_NUMBER:id_активации:телефон. Цена в этот момент резервируется на балансе, но ещё не списывается. Если передать в maxPrice максимальную приемлемую цену, то при её превышении номер не выдаётся, а в ответе приходит WRONG_MAX_PRICE:цена.

curl "https://turonay.com/stubs/handler_api.php?api_key=YOUR_KEY&action=getNumber&service=wa&country=62&maxPrice=20"
ACCESS_NUMBER:184213:905301234567

3. Получите код

Пока кода нет, getStatus возвращает STATUS_WAIT_CODE; когда код придёт — STATUS_OK:код. Именно в этот момент оплата становится окончательной. Вместо опроса можно использовать подписанные вебхуки.

curl "https://turonay.com/stubs/handler_api.php?api_key=YOUR_KEY&action=getStatus&id=184213"
STATUS_WAIT_CODE

curl "https://turonay.com/stubs/handler_api.php?api_key=YOUR_KEY&action=getStatus&id=184213"
STATUS_OK:123456

Нужен JSON? getNumberV2

getNumberV2 принимает те же параметры, что и getNumber, и при успехе возвращает JSON: id активации, номер телефона, цену, валюту (949 = TRY), страну, время окончания и оператора. Поля activationTime и activationEndTime заданы по времени сервера (Europe/Istanbul, UTC+3) в формате Y-m-d H:i:s без указания часового пояса. При ошибке приходят классические текстовые коды (NO_NUMBERS, NO_BALANCE, WRONG_MAX_PRICE:цена).

{
  "activationId": "184213",
  "phoneNumber": "905301234567",
  "activationCost": "12.50",
  "currency": 949,
  "countryCode": "62",
  "canGetAnotherSms": true,
  "activationTime": "2026-10-10 12:00:00",
  "activationEndTime": "2026-10-10 12:20:00",
  "activationOperator": "any"
}

Почему API виртуальных номеров Turonay

Цель — короткая интеграция и предсказуемые расходы.

Методы API

В каждом запросе передаются api_key и action. В таблице ниже собраны все action с типичными ответами; подробности — на странице «Справочник API».

Оплата: резерв, списание, возврат

В Turonay за виртуальный номер платят в момент получения кода, а не выдачи номера, поэтому деньги не теряются на недоставленных активациях. Схема состоит из четырёх состояний:

Ограничение цены: maxPrice

Баланса должно хватать на цену номера, иначе вернётся NO_BALANCE. Чтобы защититься от неожиданного роста цены, передавайте maxPrice: если текущая цена выше, покупка не выполняется, а реальная цена приходит в ответе WRONG_MAX_PRICE:цена.

Вебхуки: уведомление о коде на ваш сервер

Вместо того чтобы каждую секунду вызывать getStatus, укажите HTTPS-адрес. Когда приходит код или активация отменяется, Turonay отправляет туда подписанный POST. Уведомление ставится в очередь, как только код записан, и обычно доставляется в течение 1–2 минут; опрос getStatus остаётся альтернативой и запасным вариантом. Адрес и секрет настраиваются в профиле, там же можно отправить тестовое событие.

• Подпись: HMAC-SHA256 от строки timestamp.body в заголовке X-Turonay-Signature.
• Заголовки: X-Turonay-Event, X-Turonay-Timestamp, X-Turonay-Signature, X-Turonay-Delivery.
• Принимаются только адреса https.
• Неудачная доставка повторяется до 8 раз с нарастающими паузами; одно и то же событие может прийти повторно, поэтому делайте обработчик идемпотентным.

POST /your-webhook HTTP/1.1
X-Turonay-Event: code_received
X-Turonay-Timestamp: 1791631200
X-Turonay-Signature: sha256=<hex>
X-Turonay-Delivery: dlv_<id>

signature = HMAC_SHA256(secret, timestamp + "." + body)

Примеры проверки подписи, схему данных и правила повторов смотрите в разделе «Вебхуки SMS API».

Примеры на вашем языке

Один и тот же сценарий (получить номер, дождаться кода, завершить) разобран на готовых примерах для трёх языков.

Переходите с другого API SMS-активаций?

Turonay совместим с распространённым протоколом handler_api. Если вы переходите от другого провайдера, использующего его, и ваш бот, панель или скрипт написаны под этот протокол, переход обычно сводится к трём изменениям: базовый адрес, API-ключ и сверка кодов сервисов и идентификаторов стран. Перед запуском в работу обязательно проверьте весь сценарий.

Turonay — самостоятельный сервис. Он не связан с другими провайдерами и не заявляет, что заменяет их. Перенос баланса невозможен: счёт в Turonay пополняется отдельно.

Цены и оплата

Цены зависят от сервиса и страны и постоянно обновляются, поэтому вместо фиксированного списка актуальное значение читается через getPrices. Свежие примеры и расчёт стоимости — на странице «Цены SMS API». Все суммы в API указаны в TRY; на сайте можно смотреть TRY, USD или RUB.

Баланс пополняется на странице «Оплата» банковской картой (Shopier, Stripe), криптовалютой (Cryptomus, Heleket) или банковским переводом; доступные способы зависят от валюты и региона. Отдельной платы за доступ к API нет.

Перепродавайте со своей наценкой

Если вы продаёте SMS-активации клиентам через Telegram-бота, панель или сайт, на странице «Реселлерам SMS» разобраны скидки по уровням и расчёт наценки.

Ресурсы для разработчиков

Готовые файлы, которые ускорят интеграцию:

• Описание OpenAPI (openapi.json)
• Коллекция Postman

Полный справочник методов и кодов ошибок: «Справочник API».

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

Начните интеграцию

Зарегистрируйтесь бесплатно, пополните баланс и получите первый номер за несколько минут.