📚 Документация
Полное руководство по настройке, управлению и использованию системы приема донатов
🔎 Обзор
ForgePAY — готовый инструмент для продажи привилегий, подписок и донатов прямо в Telegram. Клиент выбирает товар, оплачивает удобным способом и получает выдачу автоматически — без вашего участия.
Бот подходит владельцам игровых серверов, сообществ и авторских проектов. Вы задаёте тексты, цены и способы оплаты, а дальше система работает 24/7 и присылает вам отчёты.
✨ Ключевые возможности
- Оплата без барьеров. Подключайте встроенные платёжные модули — пользователи оплачивают так, как им удобно.
- Подписки с автопродлением. Настройте тарифы, период, напоминания и тексты — бот сам напомнит о платеже и продлит доступ.
- Акции и промокоды. Запускайте распродажи, персональные предложения и подарочные купоны, ограничивая срок действия и количество активаций.
- Автоматическая выдача на сервер. RCON-интеграция моментально выдаёт привилегии и ведёт журнал доставок, а при необходимости позволяет откатить выдачу.
- Прозрачный сбор средств. Включите прогресс-бар цели и показывайте аудитории, сколько осталось до результата.
- Лояльность и вовлечение. Реферальная программа, кешбек, таблица лидеров и персональные сообщения помогают удерживать аудиторию.
- Готовность к росту. Мультиязычность, настраиваемые сценарии и расширения позволяют развивать проект вместе с ботом.
🎯 Как бот помогает
Экономит время владельца
- Покупатель проходит весь путь внутри Telegram: выбирает товар, оплачивает и получает выдачу автоматически.
- Настраиваемые шаблоны сообщений экономят часы на переписку и ответы на повторяющиеся вопросы.
- Автоматическая выдача и возвраты исключают ручную работу и человеческий фактор.
Увеличивает доход
- Все популярные способы оплаты доступны сразу, поэтому конверсия не падает из-за отсутствия нужного метода.
- Подписки, акции, кешбек и рефералы мотивируют пользователей покупать чаще и приглашать друзей.
- Таблица лидеров и прогресс-бар сборов создают соревновательный эффект и повышают средний чек.
Готов к росту проекта
- Запускается локально (Python) или в Docker/Compose на любом сервере/VPS — выбирайте удобный вариант.
- Встроенный мониторинг подскажет, что пошло не так, и предложит решение.
- Функциональность расширяется: можно добавлять новые провайдеры, языки и сценарии под ваш бизнес.
⚡ Быстрый старт
- Получите токен бота в BotFather и запишите его в файл
.env.
- Скопируйте шаблон настроек. Сделайте копию
.env.example → .env, оставьте рядом config.yml.
- Включите способы оплаты. Для каждого провайдера есть блок в
config.yml — установите true и добавьте ключи.
- Запустите бота. Для тестов используйте локальный запуск, для рабочего окружения — Docker или VPS (см. следующий раздел).
- Проверьте сценарий покупки. Используйте Sandbox-оплату, убедитесь, что выдача проходит, и только потом подключайте реальные платежи.
После запуска добавьте бота в нужный чат или канал и выдайте ему права администратора.
🔐 Лицензирование
Для работы бота необходима действующая лицензия. Каждая лицензия привязана к уникальному устройству (HWID) и обеспечивает доступ ко всем функциям системы.
📋 Как получить лицензию
- Свяжитесь с нами. Напишите в Telegram: @darkfort для приобретения лицензии.
- Укажите данные. Сообщите, на сколько устройств требуется лицензия и ваши контактные данные.
- Получите ключ. После оплаты вы получите уникальный лицензионный ключ для активации бота.
🔑 Куда вставлять лицензионный ключ
Лицензионный ключ необходимо указать в файле .env в параметре LICENSE_KEY:
# Лицензирование
LICENSE_KEY=your-license-key-here
Без действующей лицензии бот не запустится. При первом запуске система автоматически проверит лицензию и привяжет её к устройству.
💻 Привязка к устройству
Одна лицензия = одно устройство
- Каждая лицензия работает только на одном устройстве (компьютере/сервере).
- Привязка происходит автоматически при первом запуске по уникальному идентификатору оборудования (HWID).
- Попытка использовать лицензию на другом устройстве будет заблокирована системой защиты.
Расширение на несколько ПК
- Вы можете расширить лицензию для работы на нескольких устройствах одновременно.
- Каждое дополнительное устройство оплачивается со скидкой от базовой стоимости.
- Для добавления устройств свяжитесь с нами: @darkfort.
🎯 Преимущества лицензирования
- Официальная поддержка. Только лицензированные пользователи получают техническую поддержку и обновления.
- Безопасность. Защита от использования взломанных/нелегальных версий бота.
- Гибкость. Возможность масштабировать лицензию под ваши потребности (несколько серверов, резервные копии).
- Справедливая цена. Скидки на дополнительные устройства делают расширение выгодным.
🤖 Настройка через веб-интерфейс BotFather
🌐 Новый веб-интерфейс: Все настройки бота теперь делаются через удобный веб-интерфейс.
Откройте
t.me/BotFather и нажмите кнопку
"Open App".
1. Создайте бота
- Откройте @BotFather и нажмите "Open App"
- В открывшемся веб-интерфейсе нажмите "New Bot"
- Введите название бота (то, что увидят пользователи)
- Задайте username бота — должен быть уникальным и заканчиваться на
bot (например: mydonatebot)
- Скопируйте полученный API Token — он понадобится в следующем шаге
2. Сохраните токен в .env
Откройте файл .env в корне проекта и вставьте токен:
BOT_TOKEN=your_bot_token_from_botfather
Username бота определяется автоматически через API, указывать его отдельно не нужно.
3. Настройте профиль бота
- В веб-интерфейсе BotFather выберите вашего бота из списка
- Нажмите "Edit Bot"
- Заполните поля профиля:
- Name — отображаемое имя (можно изменить в любой момент)
- Description — полное описание бота (до 512 символов, показывается на странице бота)
- About — краткая подпись (до 120 символов, показывается в профиле)
- Bot Pic — загрузите логотип размером 512×512 пикселей
- Нажмите "Save"
4. Настройте команды (опционально)
💡 Автоматическая настройка: Бот автоматически синхронизирует команды при первом запуске.
Администраторы могут вручную обновить их через команду /update_bot_commands внутри бота.
Если хотите настроить команды вручную через веб-интерфейс:
- Выберите бота → "Edit Bot"
- Найдите раздел "Commands"
- Нажмите "Edit Commands"
- Добавьте команды с описаниями через форму
- Нажмите "Save"
5. Включите Inline Mode ⚠️ ОБЯЗАТЕЛЬНО
🚨 КРИТИЧЕСКИ ВАЖНО: Inline режим необходим для работы функций шаринга товаров и fundraising.
Без него пользователи не смогут делиться контентом через @ваш_бот в чатах!
- В веб-интерфейсе BotFather выберите бота → "Edit Bot"
- Найдите переключатель "Inline Mode"
- Включите его (переключатель станет зеленым)
- Нажмите "Save"
6. Проверьте работу Inline режима
- Откройте любой чат в Telegram (можно "Избранное")
- Введите
@ваш_бот_username и добавьте пробел
- Должен появиться список доступного контента: fundraising кампании, товары из каталога, реферальные ссылки
⚠️ Если список не появляется, убедитесь что Inline Mode включен в настройках бота и перезапустите бота.
Дополнительные настройки (опционально)
В веб-интерфейсе BotFather доступны дополнительные настройки:
- Group Privacy — отключите, если бот должен читать все сообщения в группах (не только команды и упоминания)
- Inline Feedback — процент запросов inline-статистики (рекомендуется оставить 100%)
- Menu Button — добавьте кнопку меню в нижней части чата с ботом
- Payment Provider — можно настроить провайдера платежей Telegram (не требуется для этого бота)
✅ Готово! Базовая настройка бота завершена. Теперь можно переходить к настройке .env и запуску.
🚀 Запуск: локально и Docker
📦 Требования
- Локальный запуск: Python 3.9+, pip, виртуальное окружение (опционально)
- Docker: Docker Engine 20.10+, Docker Compose 2.0+
💻 Локальный запуск
Вариант 1: pip (стандартный)
# 1. Установка зависимостей
pip install -r requirements.txt
# 2. Запуск бота
python main.py
Вариант 2: Poetry (рекомендуется)
# 1. Установка зависимостей
poetry install
# 2. Запуск бота
poetry run python main.py
Логи сохраняются в папку logs/. При использовании SQLite база данных создаётся в data/bot.db.
🐳 Docker: быстрый старт
Вариант 1: SQLite (простой)
# Запуск с SQLite
docker compose -f docker-compose.sqlite.yml up --build -d
# Просмотр логов
docker compose -f docker-compose.sqlite.yml logs -f
# Остановка
docker compose -f docker-compose.sqlite.yml down
Порт 8000 проброшен для webhook. Данные хранятся в томе ./data.
Вариант 2: MySQL (полный стек)
# Запуск с MySQL + phpMyAdmin
docker compose up --build -d
# Просмотр логов
docker compose logs -f telegram-donate-bot
# Остановка
docker compose down
MySQL доступен на порту 3306, phpMyAdmin на порту 8080.
🔧 Структура Docker
Тома (volumes):
./data:/app/data — база данных и файлы данных
./config.yml:/app/config.yml — конфигурация бота
./.env:/app/.env — переменные окружения
./logs:/app/logs — логи работы бота
Изменения в конфигурации применяются без пересборки образа — достаточно перезапустить контейнер.
🔄 Обновление бота в Docker
# 1. Остановить контейнеры
docker compose down
# 2. Обновить код
git pull
# 3. Пересобрать образ
docker compose build
# 4. Запустить заново
docker compose up -d
🛠️ Управление базой данных
SQLite
База данных находится в файле data/bot.db. Для просмотра используйте SQLite браузер или CLI:
sqlite3 data/bot.db
MySQL + phpMyAdmin
При запуске полного стека автоматически доступен phpMyAdmin:
- URL:
http://localhost:8080
- Сервер:
mysql
- Пользователь: из
MYSQL_USER
- Пароль: из
MYSQL_PASSWORD
🔍 Мониторинг и отладка
# Просмотр логов в реальном времени
docker compose logs -f telegram-donate-bot
# Проверка статуса контейнеров
docker compose ps
# Вход в контейнер для отладки
docker compose exec telegram-donate-bot bash
# Просмотр использования ресурсов
docker stats telegram-donate-bot
🐛 Устранение неполадок
Проблемы с базой данных
- Проверьте параметры подключения в
.env
- Убедитесь, что контейнер БД запущен:
docker compose ps
- Проверьте логи контейнера БД:
docker compose logs mysql
Проблемы с правами доступа
Если возникают ошибки доступа к файлам:
# Linux/macOS
sudo chown -R $(id -u):$(id -g) data/
# Windows (PowerShell от администратора)
icacls data /grant:r "%USERNAME%:(OI)(CI)F" /T
🔐 Безопасность Docker
- Не храните секреты в образе. Используйте
.env для токенов и паролей.
- Регулярно обновляйте базовый образ Python:
docker compose build --pull
- Проверяйте логи на подозрительную активность:
docker compose logs | grep ERROR
- Ограничьте доступ к портам. Не открывайте порты БД наружу без необходимости.
💡 Для продакшена рекомендуется использовать Docker Compose с MySQL — это обеспечивает лучшую производительность и надёжность по сравнению с SQLite.
📡 Webhook vs Polling
- Polling (по умолчанию): просто запускайте
python main.py или контейнеры.
- Webhook: укажите
WEBHOOK_HOST (домен без протокола), опционально WEBHOOK_PATH и WEBHOOK_PORT. Организуйте SSL/Reverse proxy на уровне инфраструктуры.
🙋 Команды (пользователь)
/start — приветствие и главное меню
/settings — настройки пользователя
/rules — правила/условия
/support — контакт поддержки
/help — помощь
/my_promos — персональные промокоды
/referral — реферальная информация
/invoice — создать/получить счет на оплату (если включено)
/invoices — мои счета/история инвойсов (если включено)
🛠️ Команды (администратор)
Доступ ограничен bot.admin_ids в config.yml.
📋 Главное меню /admin
Команда /admin открывает центральную панель управления с кнопками быстрого доступа ко всем административным функциям. В шапке меню отображаются ваши данные: ID, username и имя.
🛍️ Товары
Управление каталогом товаров, настройка цен, описаний, ограничений и аудит изменений.
🧾 Аудит админов
Журнал всех действий администраторов с возможностью фильтрации и поиска. Управление списком админов: добавление и удаление.
👤 Пользователи (whois)
Подробная информация о пользователе через команду /whois + ID/username/ник. Доступные действия для пользователя:
- Покупки — история всех покупок
- Кешбек — пополнение, списание, установка баланса
- Пожертвования — история донатов
- Подписки — управление активными подписками
- Промокоды — персональные промокоды
- Sorry бонус — компенсация пользователю
- Редактирование ника — изменить Minecraft ник
- Редактирование ДР — установить дату рождения
- Сброс реферала — отвязать от реферера
📦 Список доставок
История и очередь выдачи товаров. Фильтры по статусу, дате, пользователю. Экспорт в файл. Доступные команды для управления доставками:
/delivery_retry — повторить неудавшуюся выдачу
/delivery_cancel — отменить выдачу
/delivery_status — статус конкретной выдачи
📊 Статистика
Общая статистика бота: количество пользователей, покупок, доход, популярные товары, активность по датам.
🏆 Таблица лидеров
Топ донатеров с управлением: включение/выключение отображения, настройка минимального количества донатеров для показа.
🤝 Реферальная система
Управление реферальной программой: включение/выключение, настройка бонусов для приглашающего и приглашённого. Статистика рефералов.
🎟 Управление акциями
Создание и управление акциями: скидки по расписанию, персональные предложения, лимиты активаций.
🔒 Список блокировок
Статистика заблокированных пользователей, поиск по ID/username.
🧾 Счета
Управление счетами на оплату:
- 📄 Список счетов — все созданные счета
- 🔍 Проверить счёт — статус по ID
- ➕ Создать счёт — выставить счёт пользователю
🏷️ Промокоды
Доступ через меню /admin → «🏷️ Управление акциями». Список всех промокодов, сводка по использованию, создание новых кодов.
🖥️ RCON команды
Интеграция с Minecraft серверами:
- Статус подключения — проверка онлайн серверов
- Метрики — статистика выполнения команд
- Статус кэша — информация о кешировании
- Выполнение команд — интерактивное меню для ручных команд
💳 Платежные системы
Управление платёжными провайдерами: включение/выключение, настройка параметров. Возвраты:
/refund_stars — возврат Telegram Stars по purchase_id или user_id + charge_id
/refund_stars_by_id — быстрый возврат Stars по purchase_id
🎯 Сбор средств
Управление fundraising кампаниями: установка цели, статистика сбора, сброс прогресса, переключение отображения.
🎂 Дни рождения
Статистика по дням рождения пользователей, управление автоматическими промокодами, настройка скидок.
🔄 Обновить конфиг
Перезагрузка конфигурации без перезапуска бота. Применяет изменения из config.yml и products.yml.
🛠 Обновить команды
Обновление списка команд бота в BotFather. Применяет изменения из кода без ручной настройки.
📤 Экспорт всех пользователей
Выгрузка базы пользователей в TXT-файл с ID, username, именами и датами регистрации.
⚙️ Дополнительные команды
/maintenance — включить/выключить технический режим. Блокирует доступ обычных пользователей к боту с настраиваемым сообщением.
/whois + ID/username/ник — быстрый доступ к информации о пользователе вне меню /admin.
/chatid — получить ID текущего чата/группы для настройки .env файла.
💬 Команда /chatid — Получение Chat ID
Команда /chatid предназначена для быстрого получения информации о текущем чате и создания готовой конфигурации для .env файла.
📋 Как использовать
- Отправьте команду
/chatid в любом чате:
- В личных сообщениях с ботом
- В группе (обычной или супергруппе)
- В канале (если бот администратор)
- Бот ответит с полной информацией о чате
- Скопируйте нужные значения в
.env
📊 Пример вывода
💬 Информация о чате:
📋 Chat ID: -1002395851477
📂 Тип: supergroup
📌 Название: My Group Chat
👤 Ваш ID: 123456789
🏷️ Username: @myusername
━━━━━━━━━━━━━━━━━━
📝 Конфигурация для .env:
CHAT_ID=-1002395851477
ADMIN_IDS=123456789
🔧 Применение в .env файле
После получения Chat ID добавьте его в файл .env проекта:
# Основной чат для уведомлений/логов
CHAT_ID=-1002395851477
# ID администраторов (через запятую)
ADMIN_IDS=123456789,987654321
# Для публичных каналов (если бот публикует туда донаты)
CHANNEL_ID=-1001234567890
💡 Совет: Команда работает только для администраторов бота (указаны в ADMIN_IDS). Обычные пользователи не смогут использовать эту команду в целях безопасности.
🎯 Зачем нужен Chat ID
- Логи в группу — отправка системных уведомлений в администраторскую группу
- Публикация донатов — автоматическая публикация крупных покупок в канал
- Алерты — уведомления о проблемах, ошибках, рефандах
- Команды из группы — некоторые админские команды работают из групп
💡 Все основные функции управления доступны через единое меню /admin — не нужно запоминать десятки команд, просто используйте кнопки.
🛍️ Управление товарами и разделами
Система управления товарами позволяет создавать, редактировать и организовывать каталог продуктов с поддержкой множественных языков и типов доставки.
📦 Типы товаров
Бот поддерживает различные типы товаров для гибкой настройки каталога:
🎁 Одноразовые товары (one_time)
- Покупаются один раз и выдаются немедленно
- Идеально для привилегий, донат-валюты, кейсов
- Поддержка количества в заказе
🔄 Подписки (subscription)
- Периодические платежи с автоматическим продлением
- Настройка периода действия (дни/месяцы)
- Уведомления об истечении
⏰ Лимитированные товары (limited)
- Ограничение по количеству продаж
- Временные рамки доступности
- Отображение остатка для пользователей
- Автоматическое скрытие при исчерпании лимита
🎯 Донаты (donation)
- Свободная сумма платежа
- Участие в таблице лидеров
- Опциональная выдача товаров
🔢 Переменные товары (variable)
- Пользователь выбирает количество при покупке
- Цена зависит от выбранного количества
- Идеально для донат-валюты, ресурсов
- Можно указать минимум и максимум количества
🗂️ Разделы каталога
Организуйте товары по категориям для удобной навигации:
- Создание разделов. Через меню
/admin → «🛍️ Товары» → «Управление разделами».
- Названия и описания. Поддержка мультиязычности — каждый раздел может иметь переводы.
- Сортировка. Настраиваемый порядок отображения разделов и товаров внутри них.
- Вложенность. Товары привязываются к разделам через параметр
category_id.
✏️ Создание и редактирование товаров
Доступ: /admin → «🛍️ Товары» → «Управление товарами».
Основные параметры
id — уникальный идентификатор товара
title — название (поддержка локализаций)
description — описание товара
price_usd — цена в долларах США (базовая валюта)
category_id — привязка к разделу
type — тип товара (one_time/subscription/limited/donation)
visible — видимость в каталоге (true/false)
Параметры доставки
delivery_method — метод доставки: rcon, api, manual, none
delivery_identifier_type — идентификатор для доставки: nickname или email
rcon_commands — команды для RCON выдачи (если метод rcon)
rollback_commands — команды отката (если метод rcon)
requires_minecraft_nick — требовать Minecraft ник
Параметры для лимитированных товаров
Для товаров типа limited доступны дополнительные настройки:
max_quantity — максимальное количество продаж (null = без ограничений)
available_from — дата начала доступности (ISO 8601 формат)
available_until — дата окончания доступности (ISO 8601 формат)
show_remaining — показывать остаток пользователям (true/false)
- id: limited_case
title: "Новогодний кейс"
type: limited
price_usd: 5.0
max_quantity: 100
available_from: "2025-12-25T00:00:00"
available_until: "2026-01-10T23:59:59"
show_remaining: true
Параметры для подписок
Для товаров типа subscription:
subscription_duration_days — длительность подписки в днях
subscription_auto_renew — автоматическое продление (true/false)
subscription_reminder_days — за сколько дней напомнить об истечении
🌍 Локализация товаров и разделов
Бот поддерживает мультиязычность для всех текстовых элементов каталога.
Редактирование через админ-панель
- Откройте
/admin → «🛍️ Товары»
- Выберите товар или раздел для редактирования
- Нажмите «🌍 Локализации»
- Выберите язык из списка доступных
- Введите переведённое название и описание
Ручное редактирование в products.yml
Локализации хранятся в секции localizations для каждого товара:
- id: vip_rank
title: "VIP статус" # русская версия по умолчанию
description: "Премиум привилегии на сервере"
price_usd: 10.0
# Локализации
localizations:
uk:
title: "VIP статус"
description: "Преміум привілеї на сервері"
en:
title: "VIP Rank"
description: "Premium privileges on the server"
Доступные языки
По умолчанию поддерживаются следующие языки:
- ru — Русский (по умолчанию)
- uk — Українська (украинский)
- en — English (английский)
Для добавления новых языков обратитесь к документации по локализации или в техподдержку.
🔧 Аудит изменений
Все изменения товаров и разделов логируются в систему аудита:
- Кто и когда внёс изменения
- Что именно было изменено (diff)
- Возможность отката изменений
- Доступ через
/admin → «🧾 Аудит админов»
💡 Советы по организации каталога
- Используйте понятные ID. Например,
vip_1month вместо item_42.
- Группируйте по смыслу. Создавайте разделы «Привилегии», «Валюта», «Кейсы» для удобной навигации.
- Заполняйте описания. Подробное описание товара снижает количество вопросов в поддержку.
- Локализуйте контент. Даже базовый перевод на русский значительно улучшает пользовательский опыт.
- Тестируйте перед публикацией. Используйте
visible: false для скрытых товаров при настройке.
- Используйте лимитированные товары для событий. Временные товары создают ощущение срочности и повышают конверсию.
💡 Совет: Для массовых изменений товаров удобнее редактировать файл products.yml напрямую, а затем обновить конфигурацию через /admin → «🔄 Обновить конфиг».
💳 Платежи и донаты
Бот уже подключен к популярным платформам: достаточно получить ключи, указать их в конфигурации — и донаты готовы к приёму.
Текущие платёжные решения
- CryptoBot — официальное крипто-API Telegram с поддержкой TON, USDT, BTC и мгновенными чеками в чате.
- CrystalPay — российский сервис для приема криптовалютных платежей и платежей с карт РФ (СБП). Поддерживает USDT, BTC, ETH, LTC и другие криптовалюты.
- Telegram Stars — внутренняя валюта Telegram для продажи цифровых товаров в ботах и каналах.
- Monobank — украинский банк, сбор пожертвований через банку и моментальные уведомления по API.
- Heleket — криптовалютные платежи (TON, USDT, BTC) с гибкими курсами и webhooks.
- Sandbox — тестовый режим без реальных списаний.
Если вашей аудитории нужен иной провайдер, напишите в поддержку — добавим интеграцию.
Что настроить
- Включите нужные сервисы в
.env и config.yml, пропишите токены, ключи и открытые URLs.
- Активируйте подписки, кешбэк и другие функции через блоки
subscriptions и payment_providers.
- Для тестов переключитесь в режим
Sandbox через админ-команду, чтобы не тратить реальные средства.
Каждое встроенное решение работает без обязательного открытия ФОП или ИП — подключили и сразу принимаете платежи.
💱 Валюты
Бот поддерживает отображение цен в четырех валютах: USD (доллары), EUR (евро), UAH (гривны) и RUB (рубли). Пользователь может выбрать удобную валюту в настройках (/settings → «💱 Валюта»).
Как работает
- Все цены в базе данных хранятся в USD.
- При отображении пользователю цены автоматически конвертируются в выбранную валюту.
- Каждый пользователь видит цены в своей валюте без влияния на других.
- Вы можете включать или отключать валюты через
config.yml (currency.enabled_currencies).
Курсы валют
- USD ↔ UAH: динамический курс через Monobank API (обновляется каждые 10 минут).
- EUR ↔ USD: динамический курс через Monobank API (обновляется каждые 10 минут).
- USD ↔ RUB: фиксированный курс из конфигурации (
currency.usd_rub_rate в config.yml).
- При недоступности API используются fallback-курсы из конфигурации.
Настройка: установите курс RUB в config.yml → currency.usd_rub_rate (по умолчанию 95.0). Курсы UAH и EUR обновляются автоматически через Monobank API и кешируются в конфиг (currency.usd_uah_rate_cache и currency.usd_eur_rate_cache). Если API недоступен, используются последние кешированные значения из конфига.
💡 Если вашим пользователям нужна дополнительная валюта, обратитесь в техническую поддержку — добавим интеграцию.
🛑 Технический режим
Позволяет быстро перевести бота в режим обслуживания, скрыв покупки и ограничив действия пользователей, пока вы вносите изменения или обновляете сервер.
- Включение/выключение: админ-команда
/maintenance.
- Фильтр обращений: активируется middleware, блокируя нежелательные операции.
- Гибкие тексты: сообщите пользователям о сроках работ и канале связи.
🧾 Счета на оплату
Администратор может выставить персональный счёт пользователю на товары или услуги, которых нет в обычном каталоге. Подходит для индивидуальных заказов, особых условий или уникальных предложений.
💼 Как это работает
Для администратора
- Создание счёта. Через
/admin → «🧾 Счета» → «➕ Создать счёт»
- Указание деталей. Выбор пользователя, описание, сумма, срок оплаты
- Отправка. Бот автоматически отправляет уведомление пользователю
- Отслеживание. Статус счёта обновляется автоматически при оплате
Для пользователя
- Получение уведомления. Пользователь получает сообщение со счётом
- Просмотр деталей. Описание, сумма, срок оплаты
- Оплата. Выбор удобного способа оплаты
- История. Все счета доступны через
/invoices
🛠️ Управление счетами
Доступ: /admin → «🧾 Счета»
- 📄 Список счетов — все выставленные счета с фильтрацией по статусу (ожидание/оплачен/отменён)
- 🔍 Проверить счёт — детальная информация о конкретном счёте по ID
- ➕ Создать счёт — выставить новый счёт для пользователя
- Автообновление статусов — статусы синхронизируются с платёжными провайдерами
- Напоминания — автоматические уведомления об истечении срока оплаты
💡 Примеры использования
- Индивидуальные заказы. Пользователь запросил кастомную привилегию или услугу, которой нет в каталоге
- Рассрочка/частичная оплата. Разделение крупной покупки на несколько платежей
- Особые условия. Персональная скидка или специальная цена для VIP-клиента
- Предзаказы. Выставление счёта на товар, который появится позже
- Компенсация со скидкой. После проблемы предложить товар по сниженной цене
📊 Отслеживание
Система автоматически отслеживает статусы счетов:
- Создан — счёт выставлен, ожидает оплаты
- Ожидание — пользователь инициировал оплату
- Оплачен — платёж подтверждён, товар/услуга доставлены
- Просрочен — срок оплаты истёк
- Отменён — счёт отменён администратором
💡 Совет: Используйте счета для гибкой работы с клиентами. Например, если пользователь хочет что-то особенное — выставьте персональный счёт вместо создания временного товара в каталоге.
🎂 Дни рождения
Автоматическая система поздравлений и персональных подарков для пользователей в их особенный день. Создаёт промокоды со скидками и отправляет поздравления в чат.
🎉 Как работает
Для пользователей
- Указание даты. Пользователь указывает дату рождения в настройках бота (
/settings → «🎂 Дата рождения»).
- Автоматическое поздравление. В день рождения бот отправляет поздравление с персональным промокодом.
- Простой код для ввода. Пользователь видит короткий код
HAPPYBIRTHDAY в уведомлении и в меню «Мои промокоды».
- Использование. Код можно использовать при покупке любых подходящих товаров. Принимаются оба варианта - простой и полный.
💡 UX: В базе хранится уникальный код HAPPYBIRTHDAY-{user_id}-{year}, но пользователь везде видит простой HAPPYBIRTHDAY для удобства ввода.
Настройка в config.yml
birthday:
enabled: true
# Размер скидки (15%)
discount_percent: 15
# Базовый код (простой для ввода)
base_code: "HAPPYBIRTHDAY"
# Срок действия промокода (дни)
expires_after_days: 7
# Товары, на которые действует скидка
eligible_product_ids:
- "vip_1month"
- "donation_currency"
- "premium_case"
# Минимум дней после регистрации
min_days_after_registration: 7
🛠️ Управление через админ-панель
Доступ: /admin → «🎂 Дни рождения»
- Статистика — список пользователей с датами рождения, ближайшие дни рождения
- История промокодов — список выданных кодов, статусы использования
- Ручная выдача — создание подарочного промокода для конкретного пользователя
- Редактирование ДР — изменение даты рождения через
/whois → пользователь
- Настройка скидки — изменение процента и срока действия
📊 Аналитика
- Количество пользователей с указанным днём рождения
- Статистика использования промокодов (конверсия)
- Доход от подарочных промокодов
- Ближайшие дни рождения (7-30 дней)
💡 Почему это работает
- Персонализация. Поздравление и подарок создают эмоциональную связь с проектом.
- Возвращаемость. Пользователи, получившие подарок, чаще возвращаются за покупками.
- Лояльность. Внимание к пользователю повышает удовлетворённость и доверие.
- Виральность. Пользователи делятся подарками в соцсетях, привлекая новую аудиторию.
🎁 Совет: Добавьте к поздравлению личное обращение по имени и уникальное пожелание — это усилит эффект персонализации. Можете настроить автоматическую рассылку поздравлений в определённое время (например, в 10:00 утра).
🖥️ Интеграция RCON
RCON (Remote Console) позволяет боту выполнять команды на игровых серверах Minecraft для автоматической выдачи товаров. Система поддерживает подключение к множеству серверов одновременно с балансировкой нагрузки и резервированием.
🔧 Подключение серверов
Бот поддерживает подключение к нескольким серверам одновременно. Это полезно, если у вас:
- Несколько игровых серверов (выживание, креатив, мини-игры)
- Несколько локаций одного сервера (лобби, основной мир, донат-зона)
- Резервные серверы для отказоустойчивости
- Тестовый и продакшен сервер
📝 Настройка в config.yml
Конфигурация находится в разделе rcon.servers. Каждый сервер — это отдельный блок со своими параметрами:
rcon:
enabled: true
# Список серверов
servers:
- name: "survival" # Уникальное имя сервера
host: "mc.example.com" # Адрес сервера
port: 25575 # RCON порт (по умолчанию 25575)
password: "secret123" # RCON пароль
timeout: 10 # Таймаут подключения (секунды)
retries: 3 # Количество попыток при ошибке
primary: true # Основной сервер для выдачи
- name: "creative"
host: "creative.example.com"
port: 25575
password: "creative_pass"
timeout: 10
retries: 3
primary: false # Резервный сервер
- name: "minigames"
host: "192.168.1.100"
port: 25576
password: "mini_pass"
timeout: 5
retries: 2
primary: false
# Глобальные настройки
connection_pool_size: 10 # Размер пула подключений
cache_ttl: 300 # Время жизни кеша (секунды)
enable_monitoring: true # Мониторинг статуса серверов
🎯 Как работает выдача на несколько серверов
Приоритет серверов
Система выбирает сервер для выполнения команды по следующим правилам:
- Primary сервер — сначала пытается выполнить на серверах с
primary: true
- Резервные серверы — если primary недоступен, использует остальные
- Балансировка — при нескольких primary серверах команды распределяются равномерно
- Повторные попытки — если команда не выполнилась, система пробует другие серверы
Выполнение на конкретном сервере
Для товаров можно указать, на каком сервере выполнять команды:
# В products.yml
- id: vip_survival
title: "VIP Survival"
price_usd: 10.0
rcon_commands:
- server: survival # Имя сервера
command: "lp user {nick} parent set vip"
- id: creative_fly
title: "Creative Fly"
price_usd: 5.0
rcon_commands:
- server: creative # Другой сервер
command: "pex user {nick} add fly"
📊 Мониторинг и управление
Доступ: /admin → «🖥️ RCON команды»
Доступные функции
- Статус подключения — проверка доступности каждого сервера с отметкой времени последней проверки
- Метрики выполнения — количество успешных/неудачных команд, среднее время выполнения
- Статус кэша — информация о кешированных результатах для оптимизации производительности
- Ручное выполнение команд — интерактивное меню для тестирования команд на выбранном сервере
- История выполнения — журнал всех выполненных команд с результатами
🔄 Откаты и повторные попытки
Система поддерживает откат выданных привилегий в случае ошибок или возвратов:
Автоматические откаты
- При ошибке оплаты автоматически выполняются
rollback_commands
- Откаты выполняются на том же сервере, где была выдача
- Поддержка транзакционности — если откат не удался, создаётся задача на повтор
- Логирование всех операций для аудита
Ручные откаты
Через /admin → «📦 Список доставок» → выбрать доставку → «Отменить выдачу»:
- Откат выполняется на указанном сервере
- Можно выбрать, какие команды выполнять
- История откатов сохраняется в базе
⚡ Производительность и кэширование
- Пул подключений — переиспользование TCP-соединений для снижения нагрузки
- Кэш результатов — сохранение результатов проверок статуса для быстрого доступа
- Асинхронное выполнение — команды выполняются параллельно на разных серверах
- Graceful degradation — при недоступности одного сервера система продолжает работу с остальными
🛡️ Безопасность
⚠️
Важно: RCON пароли передаются в открытом виде. Обязательно:
- Используйте сильные пароли (минимум 16 символов)
- Не используйте один пароль для всех серверов
- Ограничьте доступ к RCON порту через firewall (разрешите только IP бота)
- Регулярно меняйте пароли
- Не храните пароли в публичных репозиториях
🔍 Диагностика проблем
| Проблема |
Решение |
| Сервер недоступен |
Проверьте host:port, убедитесь что RCON включён в server.properties |
| Неверный пароль |
Сверьте rcon.password в server.properties с паролем в config.yml |
| Таймаут выполнения |
Увеличьте timeout в настройках сервера |
| Команды не выполняются |
Проверьте синтаксис команд, права RCON-пользователя, логи сервера Minecraft |
💡 Советы по настройке
- Тестируйте на dev-сервере. Настройте тестовый сервер с
primary: false для проверки команд перед продакшеном.
- Используйте переменные. В командах доступны:
{nick} (ник игрока), {quantity} (количество), {item_id} (ID товара).
- Группируйте команды. Для одного товара можно указать несколько команд — они выполнятся последовательно.
- Мониторьте статус. Регулярно проверяйте статус серверов через админ-панель, настройте уведомления о сбоях.
- Балансируйте нагрузку. Если у вас высоконагруженный проект, распределите команды между несколькими серверами.
💡 Совет: Для максимальной отказоустойчивости настройте минимум 2 сервера с primary: true. Если один упадёт, выдача будет продолжаться через второй без задержек для пользователей.
🌐 API Доставка товаров
Бот поддерживает выдачу товаров не только через RCON, но и через REST API запросы к вашему серверу.
✨ Возможности
- REST JSON API с Bearer token аутентификацией
- Единая глобальная конфигурация для всех товаров
- Настройка через админ-меню бота
- Автоматическая выдача через POST запросы
- Rollback (откат) через отдельный endpoint
- Retry логика при ошибках
- Совместимость с RCON - используйте оба метода
🚀 Быстрая настройка
1. Настройка в админ-панели бота:
Найдите кнопку "🌐 Настройки API Delivery" в главном меню админки и заполните:
- Base URL — адрес вашего API сервера
- Bearer Token — секретный токен
- Delivery Endpoint — путь для выдачи
- Rollback Endpoint — путь для отката
- Timeout — таймаут запроса (1-300 сек)
2. В товаре (products.yml):
- id: my_item
title: "Мой товар"
price_usd: 10.0
delivery_method: api # ✅
📡 Формат API запросов
POST {base_url}{delivery_endpoint}
Headers:
Authorization: Bearer {bearer_token}
Content-Type: application/json
Body (JSON):
{
"delivery_id": 123,
"purchase_id": 456,
"item_id": "example_item",
"item_title": "Пример товара",
"minecraft_nick": "Player123",
"quantity": 1,
"timestamp": "2025-01-10T12:00:00"
}
Успешный ответ: HTTP 200-299
Rollback: аналогичный формат на {rollback_endpoint}
🎯 Методы доставки
Выбор метода доставки для товара:
delivery_method: api — использует глобальные настройки API из админ-меню
delivery_method: rcon — использует RCON команды, указанные в товаре
delivery_method: manual — требует ручной выдачи администратором
delivery_method: none — без автоматической доставки
🔧 Пример комбинированной конфигурации
Разные товары могут использовать разные методы доставки:
products:
# API доставка
- id: vip_rank
delivery_method: api
delivery_identifier_type: email
# RCON доставка
- id: starter_kit
delivery_method: rcon
rcon_commands:
- command: "give {minecraft_nick} diamond 64"
# Ручная доставка
- id: special_item
title: "Особый товар"
price_usd: 50.0
delivery_method: manual
📚 Документация
📖 Подробная документация по API доставке товаров →
Узнайте, как работает система доставки, настройте endpoints, изучите примеры JSON запросов/ответов, логику повторных попыток и реализацию серверов на Python/Node.js.
💡 API доставка особенно полезна, если у вас собственная система выдачи товаров, отличная от Minecraft RCON, или если вы хотите интегрировать бота с существующим backend.
🎯 Сбор средств
Инструмент для организации целевых сборов с визуализацией прогресса и автоматическими уведомлениями. Идеален для сбора на оборудование, хостинг, развитие проекта.
🛠️ Настройка в config.yml
fundraising:
enabled: true
# Целевая сумма сбора (USD)
goal_amount: 1000.0
# Название кампании
campaign_name: "Сбор на новый сервер"
# Описание цели
campaign_description: "Нужен мощный сервер для 100+ игроков"
# Отображение прогресс-бара
show_progress_bar: true
# Путь к изображению прогресса
progress_image: "assets/fundraising_progress.png"
# Автоматические напоминания
auto_reminders: true
reminder_interval_hours: 24
📊 Как работает
Для пользователей
- Прогресс-бар отображается в главном меню
- Показывает текущую сумму и цель
- Все покупки и донаты учитываются автоматически
- Периодические напоминания о цели
Пример прогресса
🎯 Сбор на новый сервер
Собрано: $750 из $1000
🟩🟩🟩🟩🟩🟩🟩🟪🟪🟪 75%
Осталось: $250
Для администраторов
Доступ: /admin → «🎯 Сбор средств»
- Статистика сбора — текущая сумма, процент, донатеры
- Установить цель — изменение целевой суммы
- Сбросить прогресс — начать новую кампанию
- Вкл/выкл отображение — скрыть/показать прогресс
- История донатов — список всех вкладов в сбор
💡 Практические примеры
| Цель |
Сумма |
Когда использовать |
| 🖥️ Новый сервер |
$500-2000 |
Обновление или расширение инфраструктуры |
| 🎉 Проведение события |
$200-500 |
Платные плагины, призы для конкурсов |
| 🚀 Новая фича/режим |
$100-300 |
Разработка кастомного функционала |
| 🎨 Ресурс-пак |
$50-150 |
Покупка качественных текстур и моделей |
📈 Почему это работает
- Прозрачность. Люди видят, куда идут деньги и какой прогресс достигнут.
- Вовлечение. Визуализация прогресса мотивирует донатить.
- Социальное доказательство. Люди видят, что другие уже поддержали проект.
- Автоматизация. Не нужно вручную обновлять прогресс в соцсетях.
⚠️ Важно: Будьте честны с аудиторией. Если цель достигнута, обязательно сообщите об этом и покажите результат (скриншоты нового сервера, фичи и т.д.). Это укрепляет доверие и мотивирует на будущие сборы.
🤝 Рефералы и кешбек
Комплексная система лояльности для привлечения новых пользователей и стимулирования повторных покупок. Объединяет реферальную программу с бонусами за покупки.
🔗 Реферальная система
Позволяет пользователям приглашать друзей и получать бонусы с их покупок.
Как работает
- Получение ссылки. Пользователь нажимает кнопку «🤝 Реферальная программа» в меню бота или использует команду
/referral.
- Приглашение друга. Пользователь делится своей уникальной реферальной ссылкой (формат:
t.me/ваш_бот?start=ref_USER_ID).
- Регистрация реферала. Когда новый пользователь переходит по ссылке и запускает бота, система автоматически связывает его с реферером.
- Начисление бонусов. При первой покупке реферала оба получают бонусы на кешбек-баланс.
Настройка в config.yml
referral:
enabled: true
# Бонус для того, кто пригласил (USD)
referrer_bonus: 1.0
# Бонус для нового пользователя (USD)
referee_bonus: 0.5
# Минимальная сумма покупки для активации
min_purchase_amount: 5.0
# Только первая покупка реферала
first_purchase_only: true
Управление через админ-панель
Доступ: /admin → «🤝 Реферальная система»
- Включение/выключение — переключатель активности программы
- Настройка бонусов — изменение размера вознаграждений
- Статистика — топ рефереров, количество приглашений, начисленные бонусы
- Сброс реферала — через
/whois → пользователь → «Сброс реферала»
💰 Система кешбека
Автоматически начисляет бонусы на баланс пользователя с каждой покупки. Накопленный кешбек можно использовать для оплаты следующих покупок.
Как работает
- При каждой покупке система начисляет процент от суммы на кешбек-баланс
- Баланс отображается в профиле пользователя
- При следующей покупке пользователь может использовать накопленный кешбек
- Кешбек списывается автоматически или по выбору пользователя
Пример
Пользователь покупает товар за $10 с кешбеком 5%. Ему начисляется $0.50 на баланс. При следующей покупке за $8 он может использовать $0.50, заплатив только $7.50.
Настройка в config.yml
security:
cashback_enabled: true
# Процент возврата (5%)
cashback_rate: 0.05
# Минимальная сумма для начисления
min_cashback_amount: 1.0
# Максимальный баланс кешбека
max_cashback_balance: 100.0
# Срок действия кешбека (дни)
cashback_expiry_days: 365
Управление кешбеком пользователя
Администраторы могут управлять балансом через /whois → пользователь → «Кешбек»:
- Пополнить баланс — добавить бонус вручную
- Списать кешбек — убрать средства с баланса
- Установить баланс — задать точное значение
- История операций — просмотр начислений и списаний
🎯 Комбинирование систем
Реферальная программа и кешбек работают совместно:
- Реферальные бонусы начисляются на кешбек-баланс обоих пользователей
- Кешбек начисляется с каждой покупки, независимо от реферальной программы
- Можно настроить разные проценты для рефералов и обычных покупок
- Все операции логируются в базе данных для аудита
💡 Советы по настройке
- Баланс бонусов. Не делайте слишком большие проценты — это может снизить прибыль. Оптимально: 3-7% кешбек, $1-2 реферальный бонус.
- Минимальная сумма. Установите порог активации, чтобы избежать злоупотреблений мелкими покупками.
- Промо-кампании. Временно увеличивайте бонусы для привлечения пользователей на старте проекта.
- Контроль лимитов. Ограничьте максимальный баланс кешбека, чтобы пользователи не накапливали слишком много.
💡 Совет: Комбинируйте реферальную программу с акциями — например, удвойте реферальные бонусы на выходных или в праздники. Это создаст дополнительную мотивацию для привлечения новых пользователей.
🏆 Таблица лидеров
Публичный рейтинг активных донатеров создаёт соревновательный эффект и мотивирует пользователей поддерживать проект. Отображается в боте, каналах и может быть интегрирована на сайт.
🎯 Как это работает
Автоматический подсчёт
- Система автоматически суммирует все платежи пользователя
- Учитываются покупки, донаты и подписки
- Рейтинг обновляется после каждой транзакции
- Можно настроить период (за всё время/месяц/неделю)
Отображение
- В боте — топ донатеров в главном меню
- В канале — автоматическая публикация обновлённого рейтинга
- По запросу — команда для просмотра полной таблицы
Настройка в config.yml
leaderboard:
enabled: true
# Количество мест в топе
top_count: 10
# Период подсчёта
period: "all_time" # all_time/monthly/weekly
# Минимальная сумма для попадания в топ
min_amount: 10.0
# Скрывать пользователей без username
hide_without_username: false
# Автопубликация в канал
auto_publish: true
channel_id: "-100123456789"
publish_interval_hours: 24
🛠️ Управление через админ-панель
Доступ: /admin → «🏆 Таблица лидеров»
- Просмотр топа — текущий рейтинг с суммами и позициями
- Включить/выключить — переключатель отображения таблицы
- Настройка количества — изменить число отображаемых мест (3-50)
- Сброс статистики — начать новый период подсчёта (например, для месячного топа)
- Исключить пользователя — убрать из таблицы (если попросил или тестовый аккаунт)
- Опубликовать в канал — ручная публикация обновлённого топа
💎 Форматы отображения
Таблица может отображаться в разных форматах:
Компактный формат (для бота)
🏆 Топ донатеров
🥇 @username1 — $250.00
🥈 @username2 — $180.50
🥉 @username3 — $145.00
4. @username4 — $98.00
5. @username5 — $75.50
...
10. @username10 — $35.00
Расширенный формат (для канала)
🏆 Топ-10 донатеров месяца
Спасибо за поддержку проекта!
🥇 1 место — @username1
💰 $250.00 | 🛒 15 покупок
🥈 2 место — @username2
💰 $180.50 | 🛒 12 покупок
🥉 3 место — @username3
💰 $145.00 | 🛒 8 покупок
...
Статистика обновлена: 10.01.2025
🎁 Мотивация и награды
Как сделать таблицу лидеров более привлекательной:
- Награды за место. Топ-3 получают уникальные роли/привилегии на месяц
- Месячные призы. Победитель месяца получает бонус или эксклюзивный товар
- Значки отличия. Специальные эмодзи или метки для топ-донатеров в чате
- Публичная благодарность. Упоминание в постах, видео, стримах
- Процентные бонусы. Топ-3 получают повышенный кешбек (10% вместо 5%)
📊 Стратегии использования
Постоянный топ (all_time)
Показывает общий вклад за всё время существования проекта.
Плюсы:
- Признание постоянных донатеров
- Стабильность позиций
- История проекта
Минусы:
- Новым сложно попасть в топ
- Может застояться
Месячный топ (monthly)
Обнуляется каждый месяц, показывает активность за текущий период.
Плюсы:
- Равные возможности для всех
- Высокая динамика и соревнование
- Мотивирует регулярные донаты
Минусы:
💡 Советы по настройке
- Комбинируйте топы. Ведите и постоянный, и месячный топ одновременно — публикуйте их в разных каналах или постах.
- Минимальный порог. Установите минимальную сумму для попадания в топ (например, $10), чтобы избежать засорения тестовыми платежами.
- Конфиденциальность. Дайте пользователям возможность скрыться из топа через настройки профиля.
- Анонсы победителей. В конце месяца делайте пост с поздравлениями и вручением наград топ-3.
- Регулярность публикаций. Публикуйте обновлённый топ еженедельно в канале, чтобы поддерживать интерес.
- Визуализация. Используйте графики и диаграммы для отображения динамики топа.
📈 Почему это работает
- Социальное доказательство. Люди видят, что другие активно поддерживают проект.
- Соревнование. Желание попасть или остаться в топе мотивирует донатить больше.
- Признание. Публичная благодарность — сильный стимул для повторных донатов.
- Статус. Попадание в топ повышает статус в сообществе.
- FOMO эффект. Боязнь упустить возможность быть в числе лучших стимулирует активность.
🎯 Кейс: Сервер Minecraft добавил месячный топ донатеров с наградами: топ-3 получают уникальные префиксы и +50% кешбека. Результат — средний чек вырос на 35%, количество донатов в месяц увеличилось на 60%. Игроки активно соревнуются за попадание в топ, создавая здоровую конкуренцию.
💸 Компенсации и возвраты
Комплексная система возврата средств и отмены выданных товаров для решения конфликтных ситуаций и ошибок. Поддерживает автоматические возвраты платежей, откаты доставок и ручные компенсации.
💳 Возврат платежей
Telegram Stars (автоматический)
Полностью автоматизированный процесс возврата встроенной валюты Telegram.
Команда: /refund_stars
Параметры:
- По ID покупки:
/refund_stars purchase_id
- По пользователю:
/refund_stars @username charge_id
- По нику:
/refund_stars nick charge_id
Быстрый возврат: /refund_stars_by_id purchase_id
Автоматически возвращает Stars и откатывает выдачу товара.
Другие провайдеры (вручную)
Для CryptoBot, CrystalPay, Monobank, Heleket возврат выполняется вручную.
Процесс:
- Найдите транзакцию в админ-панели платёжной системы
- Выполните возврат через интерфейс провайдера
- Откатите доставку через
/delivery_status в боте
- Опционально: начислите компенсацию через кешбек
Некоторые провайдеры не поддерживают автоматические возвраты через API.
📦 Управление доставками
Отмена выданных товаров и откат RCON/API команд.
Через админ-панель
Доступ: /admin → «📦 Список доставок»
- Просмотр доставки — детальная информация о выдаче (товар, пользователь, команды, статус)
- Отменить выдачу — выполнить rollback_commands на сервере
- Повторить доставку — повторная выдача при ошибке (
/delivery_retry delivery_id)
- История операций — журнал всех попыток выдачи и откатов
Через команды
/delivery_status delivery_id — получить детальную информацию о доставке
- Статус выдачи (успешно/ошибка/ожидание)
- Выполненные команды RCON/API
- Время выполнения и сервер
- Кнопки для отката или повторной попытки
/delivery_cancel delivery_id — отменить доставку
- Выполняет rollback_commands на том же сервере
- Изменяет статус доставки на "отменена"
- Логирует операцию в аудит
/delivery_retry delivery_id — повторить доставку
- Полезно при временных проблемах с RCON/API
- Повторяет все команды выдачи заново
- Обновляет статус при успехе
💰 Компенсации через кешбек
Ручная корректировка баланса лояльности для компенсации неудобств.
Доступ: /whois user_id|@username|nick → «Кешбек»
Операции с балансом
- Пополнить баланс — добавить сумму как компенсацию
- Списать кешбек — убрать средства (при злоупотреблении)
- Установить баланс — задать точное значение
- История операций — все начисления и списания
Примеры компенсаций
- Задержка доставки — начислить 10-20% от стоимости
- Ошибка выдачи — вернуть 100% + бонус 5-10%
- Технические проблемы — фиксированная сумма $1-5
- Извинения — символическая сумма для лояльности
🔄 Полный процесс возврата
Пошаговая инструкция для полного возврата покупки:
- Найти покупку. Через
/whois → пользователь → «Покупки» найти нужную транзакцию
- Проверить доставку. Через
/delivery_status delivery_id посмотреть статус выдачи товара
- Откатить выдачу. Если товар был выдан — отменить через «Отменить выдачу» или
/delivery_cancel
- Вернуть деньги.
- Telegram Stars:
/refund_stars_by_id purchase_id
- Другие провайдеры: вручную через админ-панель провайдера
- Компенсация (опционально). Начислить бонус на кешбек-баланс через
/whois
- Уведомить пользователя. Написать сообщение с объяснением и извинениями
📊 Журналы и аудит
- Журнал доставок — история всех выдач с фильтрами по статусу, дате, пользователю
- Аудит админов — логирование всех операций возврата и отмены
- История кешбека — все начисления и списания для каждого пользователя
- Экспорт данных — выгрузка журналов в файл для анализа
💡 Советы и рекомендации
- Быстрота реакции. Обрабатывайте запросы на возврат в течение 24 часов — это критично для репутации.
- Проверяйте перед откатом. Всегда используйте
/delivery_status чтобы убедиться, что товар действительно был выдан.
- Документируйте причины. В комментариях к операциям указывайте причину возврата для статистики.
- Сверхкомпенсация. Добавьте 5-10% сверху при возврате по вашей вине — это укрепляет лояльность.
- Автоматизация. Для Telegram Stars используйте быстрые команды — полный возврат за 10 секунд.
- Превентивные меры. Регулярно проверяйте логи RCON/API, чтобы предотвращать проблемы с доставкой.
⚠️ Важно: Автоматический возврат сейчас доступен только для Telegram Stars. Для остальных провайдеров (CryptoBot, CrystalPay, Monobank, Heleket) возвраты выполняются вручную через их админ-панели. После ручного возврата не забудьте откатить доставку через /delivery_status или /delivery_cancel.
💡 Совет: Создайте шаблоны сообщений для типовых ситуаций возврата (задержка, ошибка, технические проблемы). Это ускорит обработку и обеспечит единый стандарт общения с пользователями.
🧰 Диагностика
- Бот не отвечает: проверьте
BOT_TOKEN, удаление webhook при polling (логи при старте), папку logs/.
- Платежи не проходят: ключи и флаги провайдеров, доступность API, настройки в
config.yml.
- Выдача на сервер не сработала: параметры
rcon, онлайн сервера, логи RCON.