Как отправить OTP-код по SMS через API: шаблон, запрос и статусы

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

1. Создайте шаблон с переменной

Во вкладке «Шаблоны» добавьте текст с переменной вместо кода, например: «Ваш код подтверждения: {code}. Никому его не сообщайте. Название компании». Сервисный шаблон согласуется до 30 минут в рабочее время (подробнее — в статье Как создать шаблон и пройти модерацию).

2. Возьмите ключ интеграции

Профиль → «Доступ для интеграции». Тестовый ключ доступен сразу: отправка по нему не списывает деньги и не уходит оператору. Боевой ключ выдаётся после одобрения аккаунта. Подробно — в статье API: ключи и первый запрос.

3. Отправьте запрос

POST https://usms.uz/api/v1/send с заголовком Authorization: Bearer LOGIN:SECRET и телом в формате JSON:

• phone — номер получателя в международном формате, например 998901234567;
• from — имя отправителя;
• template_id — номер вашего шаблона;
• params — значения переменных, например {"code": "4821"}.

В ответе вы получите id сообщения и его статус.

4. Проверьте доставку

Статус можно запросить методом GET /status/{id} или получать уведомления на свой адрес через POST /webhook. Значения статусов — в статье Статусы сообщений и возврат денег.

Советы для OTP

• Код живёт недолго: ограничьте время действия на своей стороне.
• Не отправляйте в одном SMS ничего, кроме кода и названия сервиса.
• Для сайтов есть готовый виджет подтверждения номера — см. Интеграции USMS.
• Полная документация на девяти языках: api.usms.uz.