REST API SMS Activate App позволяет вашему коду купить личный номер, запустить проверку и прочитать код из SMS: для ваших приложений, аккаунтов и тестов.
В руководстве описан весь процесс: как выбрать номер, безопасно его купить, прочитать код OTP (одноразовый пароль) и освободить номер, когда он больше не нужен.
Когда автоматизация уместна
Автоматизация подходит для задач, которые принадлежат вам и повторяются. Три типичных случая:
- Сквозные тесты шагов с SMS в вашем собственном приложении: регистрация, вход, сброс пароля и 2FA (двухфакторная аутентификация).
- Поддержка 2FA для ваших служебных аккаунтов и внутренних инструментов.
- Шаг подтверждения внутри продукта, которым вы управляете.
Каждый номер является личным виртуальным номером. Это настоящий мобильный или местный номер из диапазона оператора связи, в зависимости от страны. Номер закреплён за вашим аккаунтом на срок 28 дней. На тот же номер приходят и последующие коды, поэтому повторное подтверждение и восстановление аккаунта работают в течение всего срока.
Есть два ограничения. После выдачи номер окончателен, и деньги за него не возвращаются. Принимает ли платформа номер, решает она сама, а не мы.
Большинство кодов приходит в течение нескольких минут после того, как платформа их отправила. Мы пока не публикуем долю доставленных сообщений, поэтому проверьте номер на нужной платформе, прежде чем строить вокруг него конвейер.
API принимает SMS. Отправлять SMS через него нельзя.
Перед началом
- Создайте бесплатный аккаунт на странице регистрации.
- Пополните баланс аккаунта.
- Создайте личный API-ключ в личном кабинете, на вкладке API-ключей, или в Telegram-боте.
Передавайте ключ в каждом запросе, включая запросы к каталогу:
Ключ расходует ваш баланс. Храните его на сервере: в хранилище секретов или в секретах CI. Никогда не размещайте его в клиентском коде и не добавляйте в коммиты репозитория.
Справочные данные:
- Базовый URL: https://api.sms-activate.app/v1/public
- Суммы указываются целым числом центов США. balanceCents: 2000 означает 20,00 $.
- Спецификация для программ: файл OpenAPI (OpenAPI 3.1).
- Документация для людей: документация API.
- Готовый навык для LLM-агентов: навык для агента.
- Лимиты: не меньше 120 запросов в минуту на аккаунт и 30 покупок в минуту. При превышении приходит ответ rate_limited с заголовком Retry-After.
Процесс подтверждения
- Вызовите GET /countries. Этот метод возвращает наличие номеров и диапазон цен по каждой стране.
- Вызовите GET /numbers/search?country=US&limit=1, чтобы выбрать доступный номер. В каждом результате есть phoneNumber и ваша цена в priceCents.
- Купите номер через POST /numbers с телом {"phone": "<phoneNumber>", "country": "US"}. Добавьте заголовок Idempotency-Key: <uuid>, чтобы повторный запрос никогда не списал деньги дважды. При успешной покупке возвращается 201 с полями number, chargedCents и balanceAfterCents. Доступны два необязательных поля: autoRenew (по умолчанию true) и note.
- Введите номер в тестируемом сценарии и запустите отправку SMS.
- Прочитайте код. Опрашивайте GET /numbers/{id}/sms для этого номера или GET /sms для всех номеров примерно раз в 5 до 15 секунд и задайте тайм-аут. У каждого SMS есть поля id, numberId, from, to, body и receivedAt; код извлеките из body. Списки разбиты на страницы по курсору: cursor, limit и nextCursor.
- Завершите работу. Отправьте PATCH /numbers/{id} с {"autoRenew": false}, чтобы отключить продление, или DELETE /numbers/{id}, чтобы освободить номер. Если набор тестов запускается каждый день, обычно проще держать один номер на продлении, чем покупать новый при каждом запуске.
Пример на curl
Первый вызов находит номер. Второй покупает его. Третий читает входящие SMS.
Замените +15551234567 номером, который вернул первый вызов. Если вы повторяете покупку после сетевой ошибки, используйте то же значение Idempotency-Key, а не создавайте новое.
Пример на Python
Эта функция ждёт код на одном номере, который у вас уже есть. Она использует библиотеку requests и берёт ключ из переменной окружения.
Если под условие могут подойти и более ранние SMS на этом номере, сравните receivedAt со временем, когда ваш тест вызвал отправку сообщения. Берите только более позднее.
Вебхук вместо опроса
Отправьте PATCH /numbers/{id} с {"forwardWebhookUrl": "https://your-app.example.com/sms"}, и каждое SMS и каждый звонок на этот номер будут отправляться на ваш сервер сразу по поступлении. Сначала адрес проверяется: он должен ответить на тестовый POST статусом 2xx.
Каждый запрос содержит заголовки x-vpn-event, x-vpn-timestamp и x-vpn-signature. Подпись вычисляется как HMAC-SHA256 от v1.<timestamp>.<raw body> с вашим секретом вебхука. Проверяйте её по исходным байтам тела и отклоняйте запрос, если метка времени отличается больше чем на пять минут.
Для теста, который запускается один раз, опрос проще. Вебхук подходит долго работающему сервису, который обрабатывает коды по мере поступления.
Обрабатывайте ошибки как ответы
У каждой ошибки одна и та же структура:
Выбирайте действие по коду в поле error, а не по HTTP-статусу. Один статус может означать разные отказы, поэтому сам по себе он не говорит, что произошло. Некоторые отказы добавляют объект details, например requiredCents и availableCents при insufficient_balance.
Какие коды обрабатывать:
- insufficient_balance: баланса не хватает на покупку. Остановитесь и пополните баланс.
- no_numbers: подходящего номера сейчас нет. Выберите другой номер или другую страну.
- number_unavailable: номер уже продан или больше не продаётся. Выполните поиск заново.
- validation_failed: в теле запроса или в параметрах ошибка, либо у покупки нет Idempotency-Key. Исправьте входные данные.
- idempotent_replay: запрос с этим Idempotency-Key пришёл с другим телом или ещё обрабатывается. Не считайте его новой покупкой.
- rate_limited: слишком много запросов. Подождите столько, сколько указано в заголовке Retry-After.
- priceexceeded и providerfailure: прочитайте message, покажите его и остановите запуск. После provider_failure проверьте свои номера, прежде чем покупать снова.
Ни одну из этих ошибок не нужно повторять вслепую: это не сбой. Покажите ошибку тому, кто запускает код, или остановите запуск. Сохраняйте reqId в логах. По нему поддержка находит ваш запрос.
В наборе тестов CI
- Запускайте SMS-тесты отдельной последовательной задачей, чтобы два теста никогда не читали один и тот же код.
- Храните API-ключ как секрет CI.
- Сопоставляйте каждый код с его тестом по номеру и времени старта теста.
- Задайте тайм-аут. При его срабатывании завершайте тест с понятным сообщением, в котором указаны номер и шаг.
- Для повторных запусков держите один продлеваемый номер, а не покупайте новый каждый раз.
Полезные видео
Видео сторонних авторов о приёмах, которые используются в этом руководстве. Они объясняют общие приёмы и не рассказывают о нашем сервисе.
- Python Requests Tutorial: Request Web Pages, Download Images, POST Data, Read JSON, and More (Corey Schafer): как отправлять из Python запросы GET и POST с заголовками и читать ответы в JSON.
- Server-Sent Events Crash Course (Hussein Nasser): как устроен поток Server-Sent Events и когда он выгоднее опроса.
- Polling vs Webhooks | System Design Tradeoffs (SoftwareDude): плюсы и минусы запросов по таймеру по сравнению с получением push-уведомлений.
- Idempotency in APIs Explained | Why It Matters + Code Example (Arkynate): ключи идемпотентности и безопасные повторы запросов, с примерами кода.
- Playwright Tutorial: Re-use state & Re-use Authentication (CommitQuality): как войти один раз в наборе тестов и переиспользовать состояние авторизации, чтобы шаг с SMS выполнялся только тогда, когда без него не обойтись.
Что дальше
- Полный справочник читайте в документации API.
- Загрузите спецификацию в свои инструменты из файла OpenAPI.
- Дайте LLM-агенту готовый навык для агента.
- Актуальные цены смотрите на странице цен.
- Если вы планируете строить продукт на основе API, прочитайте обзор как зарабатывать на виртуальных номерах.