SMS Activation API: покупка номеров, статусы, webhooks и ошибки

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

Что API должен закрывать сразу

• получить доступные сервисы и страны без ручного копирования справочников;
• создать заказ номера и сохранить внешний идентификатор у себя;
• получить SMS через polling или webhook;
• понять, что делать при отсутствии номеров, таймауте или изменении цены;
• не создать второй заказ при повторе одного и того же запроса.

С чего начинается нормальная интеграция

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

• проверьте ключ и баланс перед покупкой номера;
• получите список сервисов и стран, чтобы не хардкодить значения вручную;
• используйте идемпотентность, чтобы повтор запроса не создал двойной заказ;
• заранее обработайте статусы ожидания, успешного SMS и отмены.

Polling или webhook

Для первых тестов удобно запрашивать статус заказа вручную. Но если заказов много, лучше принимать событие через webhook: когда SMS приходит на номер, система отправляет payload на ваш HTTPS-адрес. Так меньше пустых запросов и проще строить пользовательский сценарий.

Идемпотентность и повтор запроса

В реальной интеграции таймаут не всегда означает, что заказ не создан. Клиент мог не получить ответ, а сервер уже успел купить номер. Поэтому покупку лучше делать с идемпотентным ключом: повтор того же запроса должен вернуть тот же результат, а не списать баланс дважды.

Ошибки, которые стоит заложить в клиент

В боевом коде важно отличать отсутствие номера от ошибки авторизации, таймаута провайдера или слишком ранней отмены. Хорошая интеграция не «падает» на первом нестандартном ответе, а показывает понятный статус оператору или пользователю.

• Нет номеров — предложить другую страну или повторить позже.
• Таймаут провайдера — проверить статус заказа, а не сразу покупать новый.
• Цена изменилась — запросить подтверждение новой цены.
• SMS не пришла — дождаться окна ожидания и обработать отмену по правилам заказа.

Как это устроено в Hush SMS

В Hush SMS можно проверить сценарий руками в Telegram, а затем перенести его в API: те же сервисы, статусы и логика получения SMS. Документация помогает быстрее собрать первый запрос и не гадать по ответам.

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

Можно ли сначала протестировать без API?

Да. Проверьте тот же сценарий вручную в Telegram-боте, а затем перенесите его в API.

Нужно ли хранить статусы заказов у себя?

Да. Сохраняйте ID заказа, номер, статус, время создания и полученный код. Это помогает корректно обрабатывать повторы, webhooks и спорные ситуации.