API временных номеров: как подключить SMS-верификацию в своё приложение

SMS-верификация — стандарт подтверждения пользователей в современных приложениях. Но что если вашему приложению нужна обратная задача: автоматически получать SMS на виртуальные номера? Это актуально для систем автоматизированного тестирования, платформ управления аккаунтами и сервисов, интегрирующих несколько внешних платформ через виртуальные номера.

В этой статье разберём, как подключить API провайдера виртуальных номеров, автоматизировать получение SMS и выстроить надёжную архитектуру для продакшн-сценариев.

Как работает API виртуальных номеров

Провайдер предоставляет REST API, через который ваше приложение может:

• Запросить список доступных номеров по стране, оператору и поддерживаемому сервису.

• Зарезервировать (арендовать) конкретный номер на заданное время.

• Получать входящие SMS на этот номер — через polling или вебхук.

• Освободить номер после использования.

Базовый поток: бэкенд обращается к API провайдера, получает номер, передаёт его в регистрационный поток внешнего сервиса, ждёт SMS, извлекает OTP-код и использует его в нужном месте логики приложения.

Критерии выбора провайдера API

• Документация API

Ищите REST/JSON с примерами кода, SDK и Postman-коллекциями — это напрямую влияет на скорость интеграции.

• Webhook-поддержка

Push-уведомления о входящих SMS избавляют от постоянного polling. Проверьте наличие retry-логики и обязательного HTTPS.

• Охват стран

Чем больше доступных гео — тем гибче тестирование. Отдавайте предпочтение мобильным номерам, а не только VoIP.

• Rate limits

Уточните burst limit и дневные лимиты — иначе при масштабировании упрётесь в ограничения.

• SLA и аптайм

Для продакшна важна гарантированная доступность. Изучите историю инцидентов провайдера.

• Ценовая модель

Оплата за номер или за SMS влияет на управление бюджетом. Спросите о скидках при объёме.

Аутентификация запросов

Большинство провайдеров используют API-ключ, передаваемый в заголовке запроса:

Authorization: Bearer {api_key}

// или

X-API-Key: {api_key}

Правила безопасности при работе с ключом:

• Никогда не храните ключ в коде на стороне клиента (фронтенд, мобильное приложение).

• Используйте переменные окружения, а не хардкодинг.

• Для разных окружений (dev, staging, prod) — разные ключи.

• Регулярно ротируйте ключи при малейшем подозрении на утечку.

Получение номера и SMS: пошаговая логика

Шаг 1: Запрос доступных номеров

GET /api/numbers/available?country=US&service=google&type=mobile

Ответ вернёт массив доступных номеров с идентификаторами, кодом страны и временем аренды.

Шаг 2: Аренда номера

POST /api/numbers/rent

{ "number_id": "n_12345", "duration": 600 }

С этого момента все входящие SMS маршрутизируются на ваш аккаунт. Провайдер вернёт подтверждение и время истечения аренды.

Шаг 3: Получение входящих SMS

Polling (опрос):

GET /api/sms/inbox?number_id=n_12345

Ваш бэкенд периодически запрашивает новые SMS. Просто в реализации, но создаёт задержку и лишнюю нагрузку на API.

Webhook (рекомендуется):

Провайдер отправляет POST на ваш endpoint сразу при получении SMS. Пример тела вебхука:

{ "number": "+12025551234", "from": "+19998887766",

"text": "Your code is 847291", "timestamp": 1716800000 }

Шаг 4: Извлечение OTP из текста

После получения SMS извлекаем код регулярным выражением:

# Универсальный паттерн

pattern: /(?:code|kod|otp)[:\s]*(\d{4,8})/i

# Простой числовой паттерн

# pattern: /\b(\d{6})\b/

Шаг 5: Освобождение номера

POST /api/numbers/release

{ "number_id": "n_12345" }

Возвращает номер в пул и останавливает тарификацию.

Обработка ошибок и нестандартных ситуаций

1. SMS не пришло за 3 мин.: запросить новый номер, retry — ответ polling пустой

2. Номер заблокирован сервисом: сменить номер или провайдера — SMS с отказом или тишина

3. Истекло время аренды: взять новый номер, повторить цикл — статус 410 Gone / expired

4. Лимит API превышен: exponential backoff, очередь — статус 429 Too Many Requests

5. Webhook не доставлен: fallback на polling, проверить endpoint — нет входящего запроса

6. OTP не найден в тексте: логировать сырое SMS, расширить паттерн — regex не совпадает

Сравнение подходов: polling vs webhook

Polling

• Задержка получения: 5–30 сек в зависимости от интервала

• Высокая нагрузка на API из-за постоянных запросов

• Простая реализация — только доступ в интернет

• Подходит для прототипов и малых объёмов

Webhook

• Задержка до 1–2 секунд

• Минимальная нагрузка на API

• Средняя сложность — нужен публичный HTTPS endpoint

• Оптимален для продакшна и высоких объёмов

Рекомендуемая архитектура для продакшна

1. Сервис управления номерами. Отдельный модуль, отвечающий за аренду, освобождение и ротацию номеров. Ведёт внутреннюю очередь и балансирует нагрузку между несколькими провайдерами.

2. Webhook-обработчик. Принимает POST от провайдеров, верифицирует подпись (HMAC), помещает сообщения в очередь (Redis / RabbitMQ / Kafka).

3. Воркер OTP-извлечения. Читает сообщения из очереди, применяет regex-паттерны, сохраняет коды в кэш с TTL.

4. Основная бизнес-логика. Читает извлечённый OTP из кэша по идентификатору задачи.

Мультипровайдерная стратегия

В продакшн-системах не стоит зависеть от одного провайдера. Стандартная практика:

• Если провайдер A возвращает ошибку или номер недоступен — запрос уходит к провайдеру B.

• Если SMS не пришло за установленное время — автоматический retry через другого провайдера.

• Статистика успешности логируется для каждого провайдера — менее надёжные получают меньше трафика.

Безопасность: что важно не упустить

• Валидируйте вебхуки по HMAC-подписи — это защищает от поддельных запросов.

• Не логируйте OTP-коды в plaintext — маскируйте или хэшируйте при записи в лог.

• Ограничивайте TTL хранения кодов — OTP не должен жить дольше, чем в исходном сервисе (обычно 5–10 минут).

• Изолируйте окружения — тестовые номера никогда не должны использоваться в продакшне.

Заключение

Интеграция API виртуальных номеров для автоматического получения SMS — задача с чётко определёнными компонентами: аутентификация, аренда номера, получение SMS через вебхук, извлечение кода, освобождение номера. Базовая реализация занимает несколько часов.

Для надёжной работы в продакшне добавьте мультипровайдерность, retry-логику, мониторинг доставляемости и корректное логирование. Это превратит базовую интеграцию в отказоустойчивую систему.

Часто задаваемые вопросы

Как часто нужно опрашивать API при polling?

Оптимальный интервал — 5 секунд. Более частый опрос создаёт нагрузку и может упереться в rate limits. Более редкий увеличивает задержку сверх допустимого времени жизни OTP.

Что делать, если вебхук недоступен временно?

Реализуйте fallback на polling при недоступности вебхука. Также уточните у провайдера, поддерживает ли он retry-логику для вебхуков при HTTP-ошибке на вашем endpoint.

Можно ли использовать один номер для нескольких одновременных верификаций?

Нет. Каждый номер должен использоваться для одной верификационной сессии одновременно. Параллельные верификации требуют параллельного пула номеров.

Как проверить, что номер не заблокирован нужным сервисом?

Многие провайдеры публикуют статус номеров для конкретных сервисов. Также можно автоматически проверять: если SMS не пришло за 3 минуты — считать номер нерабочим для данного сервиса и брать следующий из пула.