Новая возможность подтверждения номера телефона с помощью Smart Pass

Задача

У вас есть сайт или приложение, где пользователь регистрируется или оформляет заказ. Вы хотите быть уверены, что номер телефона принадлежит именно этому человеку — чтобы не плодить фейковые аккаунты, не терять деньги на мошенниках и не тратить время поддержки на разбор спорных ситуаций.   Классический путь — отправить СМС с кодом. Но у него есть минусы: Часть пользователей бросает ввод кода на полпути. СМС требует затрат. Мошенники используют виртуальные номера. Smart Pass решает эти проблемы: система сама выбирает самый быстрый и незаметный способ проверки, а пользователь либо вообще ничего не делает, либо подтверждает вход одним касанием.

Что такое Smart Pass

Smart Pass — это умная верификация по номеру телефона. Клиент вводит номер, а система запускает каскад: Seamless — незаметно, если оператор уже знает пользователя. SIM-Push — подтверждение в одно касание. SMS-код — классический одноразовый код. Если оператор поддерживает Seamless и пользователь в мобильной сети (не в Wi-Fi и не в VPN) — проверка проходит вообще без действий со стороны пользователя. Если нет — система автоматически переходит к отправке Push, а затем на СМС. Пользователь в худшем случае вводит код, но чаще всего обходится без этого. Seamless - это способ подтверждения номера вообще без действий клиента. Исключительно исходя из имеющейся у самого оператора связи информации.    Для бизнеса: выше конверсия, меньше мошенничества, один запрос вместо трёх сервисов. Для клиента: минимум усилий — без приложений, паролей и лишних шагов.

Два способа интеграции

Smart Pass можно подключить двумя способами:   Способ Кому подходит Что нужно API + свой UI Если хотите полностью контролировать внешний вид и логику Реализовать свой фронт: лоадер, поле ввода кода, обработку статусов Готовый виджет Если хотите встроить верификацию «в одну строку» Создать задачу на backend и передать taskId в виджет   Оба способа используют одни и те же методы создания задачи и проверки кода. Разница только в том, кто рисует интерфейс — вы или виджет. Полное описание методов, полей запросов и ответов смотрите в официальной документации OpenAPI: lcab.smsint.ru/cabinet/json-doc/sender#tag/Smartpass. Ниже — только логика, рекомендации и подводные камни.

Сколько стоит

Оплата за Smart Pass списывается только за успешно запущенную задачу — то есть когда верификация реально началась и дошла до результата. Если задача не создалась (например, номер невалидный, зарубежный или уже есть активная задача на этот номер) — деньги не списываются. Стоимость не зависит от того, какой способ проверки сработал. Задача с одним Seamless, задача с Push или задача, дошедшая до СМС-кода, стоят одинаково. Вы платите за результат верификации, а не за количество задействованных методов. Тарифы индивидуальны и зависят от объёма и условий работы. Актуальную стоимость уточняйте в личном кабинете (доступно после входа в личный кабинет). Отдельно про validate: true. Если при создании задачи передать validate: true, задача не будет создана и деньги не спишутся — это режим проверки валидности номера и баланса. Удобно для тестирования интеграции.

География

На текущий момент Smart Pass работает только с номерами РФ. Если номер зарубежный — задача не создастся. В будущем география может расшириться и мы обязательно оповестим вас об этом!

Часть 1. Smart Pass API

Как это работает

Smart Pass работает по схеме «сервер-сервер». Ваш backend создаёт задачу на верификацию, получает taskId и далее узнаёт результат двумя способами: Webhook — мы сами присылаем вам уведомление об изменении статуса задачи. Опрос статуса — вы сами запрашиваете текущее состояние задачи.

Что важно помнить при создании задачи

Создать токен можно в личном кабинете в разделе «Личный кабинет и рассылки». Обязательно передайте номер абонента (recipient). Без него задача не создастся. webhookUrl — опционален. Если не укажете — результат придётся опрашивать самостоятельно через метод получения статуса. Если укажете — мы сами будем присылать события. validate: true — полезно на этапе тестирования: проверяет валидность номера и наличие баланса, но задачу не создаёт и деньги не списывает. Одна активная задача на номер. Пока предыдущая задача в процессе — создать новую для того же номера нельзя. Это защита от спама и дублей. tags — используйте для фильтрации в отчётах. Например: ["2026", "Регистрация", "Промо-акция"]. opsosAllowed / opsosDisallowed — если нужно ограничить список операторов (например, работать только с МТС).

Что важно помнить про статусы

У задачи есть несколько состояний. Полную таблицу смотрите в OpenAPI, здесь — ключевое: Задача сформирована — на этом этапе может появиться hheUri, который нужно «дёрнуть» со страницы пользователя, чтобы оператор связи узнал своего абонента. Это делается невидимой картинкой. Отправлен код — пользователю ушёл одноразовый код. Именно в этом статусе нужно вызвать проверку кода. Успешно — верификация пройдена. Ошибка — верификация не пройдена, детали придут в webhook. Отклонено — пользователь отказался или не подтвердил. На этапе «задача сформирована» задача может «зависнуть» на несколько секунд, пока идёт попытка Seamless. Если она не удалась — система автоматически переходит к Push, но статус остаётся тем же.

Что важно помнить про hheUri

hheUri — это ссылка, которую должен запросить браузер пользователя. Простой способ — создать невидимую картинку: <img src="<hheUri>" style="display:none"> Подводные камни: hheUri приходит не для всех операторов. Мелкие региональные операторы Seamless не поддерживают — сразу идёт Push. Даже если hheUri пришёл — проверка может не пройти, если пользователь в Wi-Fi или VPN. Это нормально: система продолжит каскад и отправит Push. Не блокируйте интерфейс, пока hheUri «дёргается». Это фоновая операция.

Что важно помнить при проверке кода

Проверка производится с помощью метода /smartpass/sendCode Обязательно передайте code — код, который пользователь получил в СМС. Обязательно передайте taskId — идентификатор задачи, который вы получили при создании. Вызывайте проверку кода только в статусе «отправлен код». В других статусах вернётся ошибка. Если задача просрочена — вернётся expired. Нужно создать новую задачу. Если пользователь исчерпал попытки ввода — вернётся access_denied. Нужно создать новую задачу.

Webhook: что нужно знать

Если вы указали webhookUrl при создании задачи, мы будем присылать на него POST с JSON-телом при каждом изменении статуса. Что важно: Ваш обработчик должен всегда возвращать 200 OK. Тело ответа не важно. Обрабатывайте события идемпотентно: одно и то же событие может прийти дважды. Не полагайтесь только на webhook — если ваш сервер был недоступен, событие может потеряться. Для критичных сценариев дублируйте опросом статуса. Формат тела и список возможных действий (action) смотрите в OpenAPI. Логика обработки событий: action Что делать createHheUri Передать url на фронт, чтобы браузер пользователя «дёрнул» его невидимой картинкой sendCode Показать пользователю поле ввода кода success Верификация пройдена — выдать доступ, создать аккаунт, продолжить сценарий failed Обработать ошибку: показать сообщение, предложить повторить, залогировать

Полный сценарий: сервер-сервер

Часть 2. Smart Pass Виджет

Что такое виджет Smart Pass

Готовый UI-компонент, который закрывает весь сценарий верификации: показывает лоадер, поле ввода кода, результат. Вам не нужно самостоятельно рисовать интерфейс и вызывать проверку кода — виджет сделает это сам. Подходит, если вы хотите встроить верификацию на сайт «в одну строку».

Как это работает

Виджет использует внутренний comet-канал и не обращается к вашему API. Единственное, что ему нужно — taskId, который вы создаёте на своём backend.   Важно: виджет не вызывает ваш API проверки кода. Если вы используете виджет, webhookUrl не нужен — виджет сам знает результат.

Быстрый старт

Шаг 1. Подключите скрипт

html <script src="https://lcab.smsint.ru/support/smartpass.js"></script>

Шаг 2. Добавьте контейнер

html <div id="smart-pass"></div>

Шаг 3. Создайте задачу на backend

Ваш backend создаёт задачу и возвращает taskId на фронт.

Шаг 4. Запустите виджет

html <script> SmartPass({ taskId: "4a7c3854e35faf15f72e2144d6998121", container: "#smart-pass", onSuccess: () => { alert("Номер успешно проверен!"); }, onError: (error) => { alert(error); } }); </script> Параметр Тип Обяз. Описание taskId string да Идентификатор задачи, полученный при создании container string | HTMLElement да Селектор или сам элемент, куда монтировать виджет onSuccess function нет Вызывается, когда верификация пройдена onError function нет Вызывается при ошибке. Принимает текст ошибки

Что видит пользователь

Лоадер — пока идёт проверка. Если доступен Seamless — проверка проходит незаметно, пользователь сразу видит успех. Если нужен код — виджет показывает поле ввода и кнопку «Отправить». Успех — галочка и сообщение «Проверка номера телефона пройдена успешно». Ошибка — сообщение «Не удалось проверить номер телефона».

Ограничения и подводные камни

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

Безопасность

Виджет работает через widget.me-talk.ru и не требует X-Token. taskId — единственный идентификатор, который нужен фронту.

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

Что если номер не поддерживается оператором? Система попробует Seamless, затем Push, затем СМС. Если ни один способ не сработал — задача завершится со статусом «ошибка», детали придут в webhook. Что если пользователь закрыл страницу? Проверка прерывается. При возврате придётся создать новую задачу и начать заново. Что если пользователь не ввёл код? Задача завершится по таймауту со статусом «ошибка». Детали — в webhook. Можно ли создать вторую задачу для того же номера? Нет. Пока первая задача активна, вторая не создастся — вернётся ошибка. Нужен ли webhookUrl, если я использую виджет? Нет. Виджет сам знает результат и вызовет onSuccess / onError. webhookUrl нужен только для server-to-server сценариев без виджета. Какой способ интеграции выбрать? Если хотите быстро и без своего UI — выбирайте виджет. Если нужен полный контроль над интерфейсом и логикой — используйте API напрямую. Что делать с hheUri? «Дёрнуть» его со страницы пользователя невидимой картинкой. Если пользователь в Wi-Fi или VPN — проверка может не пройти, это нормально: система продолжит каскад. Есть ли ограничения по домену для виджета? Нет, виджет можно грузить с любого сайта. Что если пользователь использует VPN? Seamless может не сработать. Система автоматически перейдёт к Push или СМС. Где смотреть полное описание методов? В официальной документации OpenAPI: lcab.smsint.ru/cabinet/json-doc/sender#tag/Smartpass. Сколько стоит Smart Pass? Оплата списывается только за успешно запущенную задачу. Стоимость не зависит от того, какой способ проверки сработал — Seamless, Push или СМС. Актуальные тарифы — в личном кабинете (доступно после входа в личный кабинет). Работает ли Smart Pass с зарубежными номерами? Пока нет — услуга доступна только для номеров РФ. Если номер зарубежный, задача не создастся.