SMS API для верификации

1. GET /api/v2/tn101/get-services — каталог с идентификатором, по которому вы будете заказывать, и текущей ценой.
2. POST /api/v2/tn101/request-number — заказать номер. Принимает service_key и необязательные state и коды регионов. Возвращает ID заказа, номер и время его истечения.
3. GET /api/v2/tn101/get-number-details — опрашивайте с order_id. pin равен null, пока код не придёт, а затем содержит его. Это самый дешёвый запрос на чтение в API, рассчитанный на вызов в цикле.
4. POST /api/v2/tn101/reject-number — освободить номер, на который ничего не пришло. Этот же вызов возвращает деньги.

В этом сценарии вам ничего не отправляется по инициативе сервера, поэтому шаг 3 — это опрос (polling). Если вы предпочитаете получать уведомления, а не спрашивать, аккаунт также отправляет вебхуки о событиях заказа — они настраиваются в панели управления.

Каждый запрос передаёт Authorization: Bearer <token>. Токены создаются в панели управления в разделе доступа к API и могут быть перевыпущены там в любой момент — перевыпуск сразу делает старый токен недействительным, поэтому сначала замените его в своей конфигурации.

Запрос без действительного токена получает 401. Заблокированный аккаунт или аккаунт с отключённым доступом к API получает 403. Когда API отключён на всём сайте, каждый эндпоинт отвечает 503, а не делает вид, что работает.

Каждый эндпоинт отвечает одними и теми же тремя полями:

data содержит полезные данные, success — булево значение для ветвления, а summery — сообщение для человека. Это написание — не опечатка на этой странице: так поле называлось в API всегда, оно есть в каждой написанной под него интеграции, и переименование сломало бы их все ради исправления одной буквы. Читайте summery.

Ошибки валидации возвращают 422, где data — объект, сопоставляющий имена полей с текстами ошибок, чтобы вызывающая сторона могла сообщить, какой именно аргумент неверен, а не просто что что-то пошло не так.

API — практичный способ прогнать регистрацию или сброс пароля через реальный маршрут оператора, а не через заглушку: закажите номер, заполните им свою форму, опросите код и проверьте, что ваше приложение делает дальше. Такой тест медленнее, чем со стабом, но он ловит то, чего стаб поймать не может: нормализацию номера, фильтрацию по типу линии и задержки доставки, с которыми реально столкнутся ваши пользователи.

Лимита запросов в секунду у API нет, но есть две квоты на заказ номеров — те же, что действуют в панели управления:

• Открытые заказы. Аккаунт может одновременно держать лишь ограниченное число забронированных номеров. Опрашивайте и освобождайте номера, а не открывайте множество заказов параллельно.
• Отменённые и истёкшие заказы за день. При превышении дневной квоты заказ номеров приостанавливается на время, а при повторных превышениях пауза увеличивается. Каждая бронь расходует реальные номера, независимо от того, пришёл код или нет, — именно это квота и защищает.

Обе квоты подробнее описаны на странице временные номера, где объясняется, как проходит заказ.