Zapnoty — OTP — коды подтверждения

OTP (одноразовые коды)

Отправка и проверка кодов подтверждения через мессенджер.

POST /v1/otp/send

Генерирует 6-значный код и отправляет подписчику.

subscriber_id string (UUID) обязательный

UUID подписчика

POST /v1/otp/send

{

"subscriber_id": "550e8400-e29b-..."

}

Ответ

{

"sent": true,

"expires_in_seconds": 300

}

POST /v1/otp/verify

Проверяет введённый код.

subscriber_id string (UUID) обязательный

UUID подписчика

code string обязательный

6-значный код от пользователя

POST /v1/otp/verify

{

"subscriber_id": "550e8400-e29b-...",

"code": "482916"

}

Ответ

✓ Код верный

{

"verified": true

}

✗ Код неверный

{

"verified": false

}

Лимиты OTP: макс. 5 попыток проверки, TTL кода — 5 минут, 1 активный код на подписчика.

POST /v1/otp/request — OTP для неподписанных

Если пользователь ещё не подписан на проект, обычный /v1/otp/send вернёт 404. Этот эндпоинт создаёт deeplink в бот, где пользователь согласится подписаться и получить код одной кнопкой.

Клиент жмёт «Получить код» на вашем сайте → вы дёргаете /v1/otp/request и получаете request_id + deeplinks.
Открываете клиенту соответствующий deeplink (Telegram или Max). Бот покажет название проекта и описание, попросит подписаться и прислать код.
Polling-ом GET /v1/otp/request/{request_id}/status ждёте status=sent — вместе с ним приходит subscriber_id.
Пользователь вводит код на вашем сайте → вы делаете стандартный POST /v1/otp/verify с полученным subscriber_id + code.

Создание запроса

channel string

Предпочитаемый канал (telegram или max). Если не указан — в ответе оба deeplink'а.

ttl_minutes integer

TTL кода в минутах, 1-30 (по умолчанию 5).

max_attempts integer

Макс попыток ввода кода, 1-10 (по умолчанию 3).

POST /v1/otp/request

{

"channel": "telegram" // optional

}

Ответ

{

"request_id": "Kq9xV3mN2pT7rL8s",

"telegram_link": "https://t.me/zapnotybot?start=otp_Kq9xV3mN2pT7rL8s",

"max_link": "https://max.ru/zapnotybot?start=otp_Kq9xV3mN2pT7rL8s",

"expires_in": 900

}

Проверка статуса

Polling каждые 1-2 секунды. Статусы: pending (ждём пользователя), sent (подписан + код отправлен), cancelled (нажал «Отмена»), expired (ссылка истекла, 15 мин).

GET /v1/otp/request/{request_id}/status

Ответ

{

"status": "sent", // pending | sent | cancelled | expired

"subscriber_id": "550e8400-e29b-...",

"channel": "telegram"

}

request_id живёт 15 минут. Если пользователь уже подписан, бот не показывает экран согласия — код отправляется сразу. Классический /v1/otp/send остаётся без изменений и быстрее, если subscriber_id уже известен.