Перейти к основному содержимому

Как работают потоки подтверждения

Ниже — что происходит на каждом шаге, с точки зрения вашего бэкенда. Общая схема одна: POST /v1/verify создаёт сессию, а результат вы узнаёте либо по вебхуку, либо опрашивая GET /v1/verify/{request_id}. Отличается только середина — то, как пользователь проходит подтверждение.

Статусы сессии: sent → delivered (необязательный) → verified, либо expired (истёк TTL) / failed (терминальная ошибка).

reverse_flash_call — без ввода кода​

Пользователь сам звонит на выданный номер, мы подтверждаем по Caller ID. Код никто не вводит.

Покажите пользователю number_to_call, а сами ждите verified (по вебхуку или опросом). Вводить код не нужно, /v1/verify/check для этого метода не используется.

telegram_otp — код из Telegram​

Мы генерируем код и доставляем его в Telegram официальным ботом; пользователь вводит код у вас, вы отправляете его на проверку.

При неверном коде ответ 400 invalid_code содержит attempts_remaining; после исчерпания попыток сессия переходит в failed.

max_bot — код в мессенджере MAX​

Мы генерируем код и доставляем его в мессенджере MAX нашим ботом. Отличие от Telegram — в ответе на POST /v1/verify приходит поле deep_link (https://max.ru/<bot>?start=<token>); покажите его пользователю ссылкой или QR-кодом. Пользователь открывает бота, жмёт «Поделиться номером» — и код приходит в MAX только после этого. Дальше как обычно: пользователь вводит код у вас, вы отправляете его на проверку.

Пользователь должен поделиться тем же номером, для которого запущена проверка, — иначе код не отправляется. Код приходит в MAX только после шага «Поделиться номером»: до этого статус sent, после доставки — delivered (и awaiting_code: true). Списание — по факту доставки: если пользователь не открыл бота или не поделился номером, оплата не взимается.

sms и flash_call — тот же ввод кода, другой канал​

Оба работают по той же схеме «код → /v1/verify/check → verified», что и Telegram выше:

  • sms — код приходит пользователю по SMS. POST /v1/verify возвращает code_length и status: sent; пользователь вводит код, вы отправляете его на POST /v1/verify/check.
  • flash_call — мы делаем звонок-сброс на номер пользователя, и код — это последние code_length цифр входящего номера. Пользователь считывает их с экрана и вводит; дальше так же через /v1/verify/check.

mts_id — подтверждение через оператора (двойной путь)​

Ключевая особенность: у mts_id два пути, и заранее не известно, какой сработает. Обычно оператор присылает подтверждение прямо на SIM — и код не нужен. Но если push не проходит (например, номер MVNO), происходит откат на SMS-OTP, и вот тогда пользователю приходит код, который нужно ввести.

Поэтому не показывайте поле ввода кода сразу. Ждите сигнала: вебхук verification.code_required или флаг awaiting_code: true в статусе. Нет сигнала — кода не будет.

Что важно учесть для mts_id:

  • Опрашивайте awaiting_code (или слушайте verification.code_required) — только по этому сигналу показывайте ввод кода. До него awaiting_code: false.
  • /v1/verify/check асинхронный. Мы ретранслируем код оператору, а окончательный результат приходит чуть позже. Поэтому ответ на check — status: sent, а не verified. Итог узнавайте по GET /v1/verify/{request_id} или вебхукам verification.verified / verification.failed / verification.expired (истечение таймаута подтверждения оператором приходит как expired).
  • Слишком ранний код (до отката) вернёт 409 not_pending.

Узнать результат: вебхук или опрос​

Оба способа рабочие, и их можно комбинировать (вебхук как основной, опрос — как страховка):

  • Вебхук — мы сами присылаем событие на ваш URL (см. Вебхуки).
  • Опрос — периодически запрашивайте GET /v1/verify/{request_id} до терминального статуса.

Источник истины при расхождениях — GET /v1/verify/{request_id}.