Промокоды

Промокоды управляются из Web App админки и применяются либо сразу, либо на checkout перед созданием платежа. Один код может объединять совместимые фиксированные бонусы (дни, обычный и premium-трафик) со скидкой или множителем срока. Несовместимые сочетания админка и API отклоняют.

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

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

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

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

Эффекты

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

Фиксированные дни, обычный и premium-трафик можно сочетать между собой. Их также можно сочетать со скидкой или множителем срока. Фиксированные бонусы нельзя сочетать с множителем трафика, потому что у этих эффектов разные правила выдачи. Фиксированный трафик поддерживается только в scope all или subscription.

Валидация не принимает пустой эффект, отрицательные значения, скидку вне диапазона 0..100, множители ниже 1 или выше лимитов из настроек. Каждый фиксированный объём трафика задаётся с точностью до 0.001 GB в диапазоне 0.001..1000000 GB. Максимумы множителей задаются переменными 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

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

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

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

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

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

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

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

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

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

• Бонусные дни после оплаты добавляются сверх оплаченного периода. Если пользователь продлевает действующие HWID-докупки вместе с подпиской, их срок также сдвигается на бонусные дни.
• Фиксированные обычные и premium GB добавляются к соответствующим carry-over балансам подписки и не пропадают при следующем продлении. Premium-бонус требует premium squads в тарифе.
• Множитель срока добавляет только дополнительные дни; сумма платежа не меняется.
• Скидка меняет только сумму платежа; выдаваемые дни или GB остаются базовыми.
• Для подписки с checkout-докупками процентная скидка считается от всей корзины: базовой цены периода, устройств, обычного и premium-трафика, включая пропорциональную доплату за немедленное повышение активного лимита. Сначала формируется subtotal, затем применяется скидка, после неё — партнёрский баланс. То же правило действует для Telegram Stars.
• Фиксированный GB-бонус промокода не меняет выбранную отметку гибкого лимита: он попадает в отдельный переносимый обычный/premium-баланс и продолжает жить по правилам бонусного трафика.
• Множитель трафика меняет только выдаваемый объем GB; сумма платежа остается базовой.
• Для traffic-тарифа повторная покупка с множителем добавляет увеличенный объем к текущему остатку по тем же правилам, что обычная покупка traffic-пакета.

Персональные предложения checkout

Расширение может зарегистрировать один или несколько персональных кодов через register_promo_checkout_suggestion_provider. Это подсказка, а не обход правил промокода: core повторно проверяет активность, лимиты, область применения, минимальную покупку и выбранный способ оплаты.

Mini App автоматически подставляет первый предложенный код, но пользователь может убрать его. Telegram-бот проверяет все предложенные коды для каждого периода подписки, показывает лучший валидный вариант в цене и даёт отключить предложение перед оплатой. Ошибка одного provider не ломает checkout: она записывается в лог, после чего проверяются остальные источники.

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

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

• 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.

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