Введение
Telegram авторизация
Промокоды

Промокоды

0.3 NEW — Альтернативная регистрация устройств по промокодам, без Telegram.

Промокоды позволяют выдавать доступ пользователям без привязки к Telegram-боту. Администратор генерирует коды, пользователь вводит код на странице авторизации — и сразу получает доступ.

Три режима авторизации

РежимОписание
TelegramСтандартный — пользователь отправляет код боту, админ одобряет
Без авторизацииTG auth отключен в конфиге — доступ открыт всем
ПромокодыАльтернатива без TG — пользователь вводит промокод P-XXXXXX

Все три режима могут работать одновременно: на странице авторизации отображается и код для Telegram-бота, и поле для промокода.

Генерация промокодов

Через админ-панель

В разделе 🎫 Промокоды (вкладка «Управление» → «Промокоды») доступна генерация и управление промокодами:

ПараметрОписаниеПо умолчанию
КоличествоСколько кодов сгенерировать (1-100)1
Срок доступаНа сколько дней выдаётся доступ30
ИспользованияСколько раз можно использовать код (1 = одноразовый)1
Срок действия кодаЧерез сколько часов код перестанет работать (0 = бессрочный)0

Через API 

# Сгенерировать 5 одноразовых кодов на 30 дней
curl -X POST "https://сервер/{admin_path}/api/promo" \
  -H "Content-Type: application/json" \
  -d '{"action":"generate","count":5,"days":30,"max_uses":1}'

# Сгенерировать многоразовый код на 90 дней (до 10 использований), действует 48 часов
curl -X POST "https://сервер/{admin_path}/api/promo" \
  -H "Content-Type: application/json" \
  -d '{"action":"generate","count":1,"days":90,"max_uses":10,"valid_hours":48}'

# Получить список всех промокодов
curl "https://сервер/{admin_path}/api/promo"

# Удалить промокод
curl -X POST "https://сервер/{admin_path}/api/promo" \
  -H "Content-Type: application/json" \
  -d '{"action":"delete","code":"P-ABC123"}'

Активация промокода

На странице авторизации

  1. Пользователь открывает Lampa и видит страницу авторизации
  2. Внизу страницы — блок «Или введите промокод»
  3. Вводит код формата P-XXXXXX и нажимает Активировать
  4. Доступ выдаётся мгновенно — без ожидания одобрения администратора

В Lampa-приложении (внешний плагин)

Аналогично: экран авторизации показывает поле промокода под основным кодом для бота.

Через API 

curl -X POST "https://сервер/tg/auth/promo" \
  -H "Content-Type: application/json" \
  -d '{"code":"P-ABC123"}'

Ответ при успехе:

{
  "ok": true,
  "token": "uuid-токен",
  "days": 30
}

Типы промокодов

Одноразовый (max_uses: 1)

Классический промокод — один код = один пользователь. Подходит для:

  • Раздача друзьям
  • Продажа доступа
  • Приглашения

Многоразовый (max_uses: N)

Один код можно использовать N раз. Подходит для:

  • Массовое приглашение (например, код для чата)
  • Ограниченная акция

Безлимитный (max_uses: 0)

Код можно использовать неограниченное число раз. Подходит для:

  • Публичный доступ с контролем (код можно отозвать в любой момент)
  • Тестирование

Формат кода

Промокоды имеют формат P-XXXXXX, где X — буквы и цифры (без I и O для избежания путаницы). Префикс P- отличает промокоды от 6-значных кодов авторизации.

Защита от брутфорса

Endpoint активации промокодов (/tg/auth/promo) защищён от перебора:

Попыток за 5 минРеакция
1–4Обычный ответ
5–9Задержка 2 сек перед ответом (throttle)
10+Автоматический бан IP

При срабатывании бана:

  • IP добавляется в список блокировок с причиной «Brute-force промокодов: N попыток за 5 мин»
  • Все дальнейшие запросы с этого IP возвращают 403 Forbidden
  • Бан виден в админке → можно разбанить вручную
  • В логах сервера: promo: IP banned for brute-force

Успешная активация промокода сбрасывает счётчик неудачных попыток.

Хранение

Промокоды хранятся в файле database/tgauth/promo_codes.json в директории сервера.

Обязательные подписки