Промокоды

Промокоды управляются из Web App админки и применяются либо сразу, либо на checkout перед созданием платежа. Один код может иметь только один основной эффект: бонусные дни, скидку, множитель срока или множитель трафика. Эффекты не складываются внутри одного промокода.

Где настраивать

Основной интерфейс - раздел Промокоды в Web App админке. Там можно:

• создать код вручную или оставить поле пустым, чтобы backend сгенерировал код автоматически;
• выбрать область применения, эффект, лимит активаций и срок действия;
• посмотреть статус, ссылки для Telegram-бота и Web App;
• открыть историю активаций с платежом, суммой скидки, выданными днями или GB;
• выключить, отредактировать или удалить код.

Telegram-админка и массовое создание остаются совместимым быстрым сценарием для старого режима: они создают коды с бонусными днями для подписок. Новые режимы скидок, множителей, областей применения и условий удобнее настраивать через Web App админку или admin API.

Эффекты

Эффект	Что делает	Где применяется
Бонусные дни	Добавляет дни к period-подписке. Может начисляться сразу или после оплаты.	Подписки на срок.
Скидка, %	Уменьшает сумму checkout перед созданием платежа. Для Stars итог не опускается ниже 1 Star.	Подписка, traffic-пакет, докупка трафика, premium-докупка, HWID-докупка.
Множитель срока	Увеличивает оплаченный срок подписки, например x2 превращает 1 месяц в 2 месяца.	Подписки на срок.
Множитель трафика	Увеличивает выдаваемый объем GB, например x2 превращает 100 GB в 200 GB.	Traffic-пакеты, обычные и premium-докупки трафика.

Валидация не принимает пустой эффект, несколько эффектов сразу, отрицательные значения, скидку вне диапазона 0..100, множители ниже 1 или выше лимитов из настроек. Максимумы задаются переменными PROMO_DURATION_MULTIPLIER_MAX и PROMO_TRAFFIC_MULTIPLIER_MAX.

Области применения

Scope	Покрывает
all	Все покупки, где выбранный эффект имеет смысл. Для множителей лучше выбирать точную область, чтобы не расходовать код на неподходящем checkout.
subscription	Покупка или продление period-подписки.
traffic	Покупка traffic-тарифа или legacy-пакета трафика.
traffic_topup	Обычная докупка трафика и premium-докупка (topup, premium_topup).
hwid	Докупка HWID-устройств. Для этой области поддерживается только скидка.

Бонусные дни и множитель срока должны использоваться для подписок. Множитель трафика должен использоваться для traffic или traffic_topup. Скидка может применяться ко всем областям, включая HWID.

Мгновенная активация и checkout

Есть два режима активации:

• Мгновенный бонус: код с bonus_days, без bonus_requires_payment и без минимальных условий. Пользователь вводит его в Telegram-боте или Mini App, и подписка сразу продлевается на бонусные дни. Если активной подписки нет, backend создает короткую bonus-подписку с лимитами основного period-доступа; при JSON-каталоге используется тариф по умолчанию.
• Checkout-код: скидка, множитель срока, множитель трафика или бонусные дни с bonus_requires_payment=true. Такой код применяется в форме оплаты. Если пользователь вводит его в Telegram-боте, бот отправляет кнопку Mini App с предзаполненным кодом.

Мгновенный бонус нельзя применить в checkout: пользователь должен активировать его отдельно. Checkout-код не выдает бонус до успешной оплаты.

Условия и ограничения

Для checkout-кодов можно задать минимальную покупку:

• min_subscription_months - минимальный срок для подписки;
• min_traffic_gb - минимальный объем GB для traffic-покупок и докупок.

Условия проверяются до создания платежа. Один пользователь может активировать один и тот же код только один раз. Если у пользователя уже есть pending-платеж с этим кодом, повторное применение блокируется, пока платеж не будет завершен или отменен. Общий лимит задается max_activations, а срок действия - valid_until.

Когда checkout создает платеж, условия промокода сохраняются в снимок платежа: эффект, скидка, область применения, минимальные требования и рассчитанная сумма. Успешный webhook использует этот снимок, поэтому уже созданный инвойс обрабатывается по старым условиям, даже если администратор позже выключил или изменил код.

Как влияет на подписки и трафик

• Бонусные дни после оплаты добавляются сверх оплаченного периода. Если пользователь продлевает действующие HWID-докупки вместе с подпиской, их срок также сдвигается на бонусные дни.
• Множитель срока добавляет только дополнительные дни; сумма платежа не меняется.
• Скидка меняет только сумму платежа; выдаваемые дни или GB остаются базовыми.
• Множитель трафика меняет только выдаваемый объем GB; сумма платежа остается базовой.
• Для traffic-тарифа повторная покупка с множителем добавляет увеличенный объем к текущему остатку по тем же правилам, что обычная покупка traffic-пакета.

Ссылки и совместимость

Админка показывает две ссылки для каждого кода:

• Telegram-ссылка вида /start promo_<CODE>;
• Web App ссылка со startapp=promo_<CODE>.

По умолчанию новые коды нормализуются в верхний регистр. Если включена совместимость Remnashop (MIGRATION_REMNASHOP_PROMO_CODE_COMPAT_ENABLED), backend сначала ищет код в исходном регистре, а затем использует обычную нормализацию. Это нужно для импортированных legacy-кодов.

Логи и безопасность

Неудачные попытки ввода промокода попадают под общий brute-force throttle email/промокодов. Подозрительный ввод может логироваться через LOG_SUSPICIOUS_ACTIVITY, а успешные мгновенные активации - через LOG_PROMO_ACTIVATIONS.

Связанные разделы: тарифы, платежи, админ-панель, переменные окружения.