Telegram Donate Bot — Документация

🔎 Обзор

Telegram Donate Bot — готовый инструмент для продажи привилегий, подписок и донатов прямо в Telegram. Клиент выбирает товар, оплачивает удобным способом и получает выдачу автоматически — без вашего участия.

Бот подходит владельцам игровых серверов, сообществ и авторских проектов. Вы задаёте тексты, цены и способы оплаты, а дальше система работает 24/7 и присылает вам отчёты.

✨ Ключевые возможности

• Оплата без барьеров. Подключайте встроенные платёжные модули — пользователи оплачивают так, как им удобно.
• Подписки с автопродлением. Настройте тарифы, период, напоминания и тексты — бот сам напомнит о платеже и продлит доступ.
• Акции и промокоды. Запускайте распродажи, персональные предложения и подарочные купоны, ограничивая срок действия и количество активаций.
• Автоматическая выдача на сервер. RCON-интеграция моментально выдаёт привилегии и ведёт журнал доставок, а при необходимости позволяет откатить выдачу.
• Прозрачный сбор средств. Включите прогресс-бар цели и показывайте аудитории, сколько осталось до результата.
• Лояльность и вовлечение. Реферальная программа, кешбек, таблица лидеров и персональные сообщения помогают удерживать аудиторию.
• Готовность к росту. Мультиязычность, настраиваемые сценарии и расширения позволяют развивать проект вместе с ботом.

🎯 Как бот помогает

Экономит время владельца

• Покупатель проходит весь путь внутри Telegram: выбирает товар, оплачивает и получает выдачу автоматически.
• Настраиваемые шаблоны сообщений экономят часы на переписку и ответы на повторяющиеся вопросы.
• Автоматическая выдача и возвраты исключают ручную работу и человеческий фактор.

Увеличивает доход

• Все популярные способы оплаты доступны сразу, поэтому конверсия не падает из-за отсутствия нужного метода.
• Подписки, акции, кешбек и рефералы мотивируют пользователей покупать чаще и приглашать друзей.
• Таблица лидеров и прогресс-бар сборов создают соревновательный эффект и повышают средний чек.

Готов к росту проекта

• Запускается локально (Python) или в Docker/Compose на любом сервере/VPS — выбирайте удобный вариант.
• Встроенный мониторинг подскажет, что пошло не так, и предложит решение.
• Функциональность расширяется: можно добавлять новые провайдеры, языки и сценарии под ваш бизнес.

⚡ Быстрый старт

1. Получите токен бота в BotFather и запишите его в файл .env.
2. Скопируйте шаблон настроек. Сделайте копию .env.example → .env, оставьте рядом config.yml.
3. Включите способы оплаты. Для каждого провайдера есть блок в config.yml — установите true и добавьте ключи.
4. Запустите бота. Для тестов используйте локальный запуск, для рабочего окружения — Docker или VPS (см. следующий раздел).
5. Проверьте сценарий покупки. Используйте Sandbox-оплату, убедитесь, что выдача проходит, и только потом подключайте реальные платежи.

После запуска добавьте бота в нужный чат или канал и выдайте ему права администратора.

🔐 Лицензирование

Для работы бота необходима действующая лицензия. Каждая лицензия привязана к уникальному устройству (HWID) и обеспечивает доступ ко всем функциям системы.

📋 Как получить лицензию

1. Свяжитесь с нами. Напишите в Telegram: @darkfort для приобретения лицензии.
2. Укажите данные. Сообщите, на сколько устройств требуется лицензия и ваши контактные данные.
3. Получите ключ. После оплаты вы получите уникальный лицензионный ключ для активации бота.

🔑 Куда вставлять лицензионный ключ

Лицензионный ключ необходимо указать в файле .env в параметре LICENSE_KEY:

# Лицензирование
LICENSE_KEY=your-license-key-here

Без действующей лицензии бот не запустится. При первом запуске система автоматически проверит лицензию и привяжет её к устройству.

💻 Привязка к устройству

🎯 Преимущества лицензирования

• Официальная поддержка. Только лицензированные пользователи получают техническую поддержку и обновления.
• Безопасность. Защита от использования взломанных/нелегальных версий бота.
• Гибкость. Возможность масштабировать лицензию под ваши потребности (несколько серверов, резервные копии).
• Справедливая цена. Скидки на дополнительные устройства делают расширение выгодным.

🤖 Настройка через BotFather

1. Создайте бота. Откройте чат с @BotFather, отправьте /newbot, задайте название и уникальный логин. В ответ BotFather пришлёт токен доступа.
2. Сохраните токен. Укажите его в переменной BOT_TOKEN файла .env. Username бота определяется автоматически через Telegram API.
3. Оформите профиль. Выполните /setname, /setdescription и /setabouttext, чтобы настроить название, описание и краткую подпись в профиле.
4. Загрузите команды. Команда /setcommands принимает список вида команда - описание, подготовьте его по разделам бота и отправьте одним сообщением.
5. Проверьте приватность. Через /setprivacy можно отключить фильтр входящих сообщений, если нужно получать всё из групповых чатов.
6. Обновите значок. Отправьте /setuserpic с квадратным логотипом (512x512) и дождитесь подтверждения.
7. Включите Inline режим. Откройте меню бота через /mybots → выберите бота → Bot Settings → Inline Mode → Turn on. Это позволит пользователям делиться товарами, fundraising и реферальными ссылками в любых чатах.

При изменении имени, иконки или команд просто повторите соответствующую команду в BotFather — обновление применяется сразу.

🔧 Как проверить Inline режим

После включения протестируйте работу:

1. Откройте любой чат в Telegram
2. Введите @ваш_бот_username (с пробелом после)
3. Должен появиться список: fundraising, приглашения в бота, товары из каталога

Если список не появляется, убедитесь что Inline Mode включен в BotFather и бот был перезапущен после изменения настроек.

🧩 .env и config.yml

🚀 Запуск: локально и Docker

📦 Требования

• Локальный запуск: Python 3.9+, pip, виртуальное окружение (опционально)
• Docker: Docker Engine 20.10+, Docker Compose 2.0+

💻 Локальный запуск

# 1. Установка зависимостей
pip install -r requirements.txt

# 2. Запуск бота
python main.py

Логи сохраняются в папку logs/. При использовании SQLite база данных создаётся в data/bot.db.

🐳 Docker: быстрый старт

# Запуск с 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

# Запуск с MySQL + phpMyAdmin
docker compose up --build -d

# Просмотр логов
docker compose logs -f telegram-donate-bot

# Остановка
docker compose down

🔧 Структура 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

🛠️ Управление базой данных

sqlite3 data/bot.db

🔍 Мониторинг и отладка

# Просмотр логов в реальном времени
docker compose logs -f telegram-donate-bot

# Проверка статуса контейнеров
docker compose ps

# Вход в контейнер для отладки
docker compose exec telegram-donate-bot bash

# Просмотр использования ресурсов
docker stats telegram-donate-bot

🐛 Устранение неполадок

# 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 — мои счета/история инвойсов (если включено)

Команды регистрируются централизованно: src/core/commands_manager.py.

🛠️ Команды (администратор)

Доступ ограничен bot.admin_ids в config.yml.

📋 Главное меню /admin

Команда /admin открывает центральную панель управления с кнопками быстрого доступа ко всем административным функциям. В шапке меню отображаются ваши данные: ID, username и имя.

⚙️ Дополнительные команды

• /maintenance — включить/выключить технический режим. Блокирует доступ обычных пользователей к боту с настраиваемым сообщением.
• /whois + ID/username/ник — быстрый доступ к информации о пользователе вне меню /admin.
• /chatid — получить ID текущего чата/группы для настройки .env файла.

💬 Команда /chatid — Получение Chat ID

Команда /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

🎯 Зачем нужен Chat ID

• Логи в группу — отправка системных уведомлений в администраторскую группу
• Публикация донатов — автоматическая публикация крупных покупок в канал
• Алерты — уведомления о проблемах, ошибках, рефандах
• Команды из группы — некоторые админские команды работают из групп

💡 Все основные функции управления доступны через единое меню /admin — не нужно запоминать десятки команд, просто используйте кнопки.

🛍️ Управление товарами и разделами

Система управления товарами позволяет создавать, редактировать и организовывать каталог продуктов с поддержкой множественных языков и типов доставки.

📦 Типы товаров

Бот поддерживает различные типы товаров для гибкой настройки каталога:

🗂️ Разделы каталога

Организуйте товары по категориям для удобной навигации:

• Создание разделов. Через меню /admin → «🛍️ Товары» → «Управление разделами».
• Названия и описания. Поддержка мультиязычности — каждый раздел может иметь переводы.
• Сортировка. Настраиваемый порядок отображения разделов и товаров внутри них.
• Вложенность. Товары привязываются к разделам через параметр category_id.

✏️ Создание и редактирование товаров

Доступ: /admin → «🛍️ Товары» → «Управление товарами».

Параметры для лимитированных товаров

Для товаров типа 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 — за сколько дней напомнить об истечении

🌍 Локализация товаров и разделов

Бот поддерживает мультиязычность для всех текстовых элементов каталога.

Редактирование через админ-панель

1. Откройте /admin → «🛍️ Товары»
2. Выберите товар или раздел для редактирования
3. Нажмите «🌍 Локализации»
4. Выберите язык из списка доступных
5. Введите переведённое название и описание

Ручное редактирование в 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 для скрытых товаров при настройке.
• Используйте лимитированные товары для событий. Временные товары создают ощущение срочности и повышают конверсию.

💳 Платежи и донаты

Бот уже подключен к популярным платформам: достаточно получить ключи, указать их в конфигурации — и донаты готовы к приёму.

Текущие платёжные решения

• CryptoBot — официальное крипто-API Telegram с поддержкой TON, USDT, BTC и мгновенными чеками в чате.
• CrystalPay — криптоэквайринг с платёжными ссылками и автоматическим контролем статуса без привлечения сторонних кошельков.
• Telegram Stars — внутренняя валюта Telegram для продажи цифровых товаров в ботах и каналах.
• Monobank — украинский банк, сбор пожертвований через банку и моментальные уведомления по API.
• Heleket — криптовалютные платежи (TON, USDT, BTC) с гибкими курсами и webhooks.
• Sandbox — тестовый режим без реальных списаний.

Если вашей аудитории нужен иной провайдер, напишите в поддержку — добавим интеграцию.

Что настроить

• Включите нужные сервисы в .env и config.yml, пропишите токены, ключи и открытые URLs.
• Активируйте подписки, кешбэк и другие функции через блоки subscriptions и payment_providers.
• Для тестов переключитесь в режим Sandbox через админ-команду, чтобы не тратить реальные средства.

Каждое встроенное решение работает без обязательного открытия ФОП или ИП — подключили и сразу принимаете платежи.

💱 Валюты

Бот поддерживает отображение цен в четырех валютах: USD (доллары), EUR (евро), UAH (гривны) и RUB (рубли). Пользователь может выбрать удобную валюту в настройках (/settings → «💱 Валюта»).

Настройка: установите курс 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 → «🏷️ Управление акциями» → «Создать промокод»

Основные параметры

• Код — уникальное название (например, NEWYEAR2025)
• Тип скидки — процент или фиксированная сумма
• Размер скидки — 20% или $5
• Доступные товары — на какие товары действует скидка
• Дата начала/окончания — срок действия
• Максимальное количество активаций — ограничение использований

📊 Примеры использования

🛠️ Управление промокодами

Доступ: /admin → «🏷️ Управление акциями» или /promo_help

• Список всех промокодов — активные, законченные, истёкшие
• Статистика использования — количество активаций, доход, конверсия
• Редактирование — изменение параметров активных кодов
• Деактивация — досрочное отключение промокода
• Планировщик — автоматическое включение/выключение по дате

💡 Советы по маркетингу

• Ограниченность. Лимиты активаций создают ощущение срочности и эксклюзивности.
• Короткие сроки. 24-72 часа — оптимальный период для максимальной конверсии.
• Комбинируйте скидки. Совмещайте процентные и фиксированные скидки для разных целевых аудиторий.
• Персонализация. Уникальные коды для VIP-пользователей повышают лояльность.
• Аналитика. Отслеживайте эффективность каждого промокода и корректируйте стратегию.

🧾 Счета на оплату

Администратор может выставить персональный счёт пользователю на товары или услуги, которых нет в обычном каталоге. Подходит для индивидуальных заказов, особых условий или уникальных предложений.

💼 Как это работает

🛠️ Управление счетами

Доступ: /admin → «🧾 Счета»

• 📄 Список счетов — все выставленные счета с фильтрацией по статусу (ожидание/оплачен/отменён)
• 🔍 Проверить счёт — детальная информация о конкретном счёте по ID
• ➕ Создать счёт — выставить новый счёт для пользователя
• Автообновление статусов — статусы синхронизируются с платёжными провайдерами
• Напоминания — автоматические уведомления об истечении срока оплаты

💡 Примеры использования

• Индивидуальные заказы. Пользователь запросил кастомную привилегию или услугу, которой нет в каталоге
• Рассрочка/частичная оплата. Разделение крупной покупки на несколько платежей
• Особые условия. Персональная скидка или специальная цена для VIP-клиента
• Предзаказы. Выставление счёта на товар, который появится позже
• Компенсация со скидкой. После проблемы предложить товар по сниженной цене

📊 Отслеживание

Система автоматически отслеживает статусы счетов:

• Создан — счёт выставлен, ожидает оплаты
• Ожидание — пользователь инициировал оплату
• Оплачен — платёж подтверждён, товар/услуга доставлены
• Просрочен — срок оплаты истёк
• Отменён — счёт отменён администратором

🎂 Дни рождения

Автоматическая система поздравлений и персональных подарков для пользователей в их особенный день. Создаёт промокоды со скидками и отправляет поздравления в чат.

🎉 Как работает

birthday:
  enabled: true
  # Размер скидки (20%)
  discount_percent: 20
  # Срок действия промокода (дни)
  promo_duration_days: 7
  # Товары, на которые действует скидка
  eligible_items:
    - "vip_1month"
    - "donation_currency"
    - "premium_case"
  # Ограничение использований
  max_uses: 1
  # Текст поздравления
  greeting_message: "🎉 С Днём Рождения!"

🛠️ Управление через админ-панель

Доступ: /admin → «🎂 Дни рождения»

• Статистика — список пользователей с датами рождения, ближайшие дни рождения
• История промокодов — список выданных кодов, статусы использования
• Ручная выдача — создание подарочного промокода для конкретного пользователя
• Редактирование ДР — изменение даты рождения через /whois → пользователь
• Настройка скидки — изменение процента и срока действия

📊 Аналитика

• Количество пользователей с указанным днём рождения
• Статистика использования промокодов (конверсия)
• Доход от подарочных промокодов
• Ближайшие дни рождения (7-30 дней)

💡 Почему это работает

• Персонализация. Поздравление и подарок создают эмоциональную связь с проектом.
• Возвращаемость. Пользователи, получившие подарок, чаще возвращаются за покупками.
• Лояльность. Внимание к пользователю повышает удовлетворённость и доверие.
• Виральность. Пользователи делятся подарками в соцсетях, привлекая новую аудиторию.

🖥️ Интеграция 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       # Мониторинг статуса серверов

🎯 Как работает выдача на несколько серверов

# В 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 команды»

Доступные функции

• Статус подключения — проверка доступности каждого сервера с отметкой времени последней проверки
• Метрики выполнения — количество успешных/неудачных команд, среднее время выполнения
• Статус кэша — информация о кешированных результатах для оптимизации производительности
• Ручное выполнение команд — интерактивное меню для тестирования команд на выбранном сервере
• История выполнения — журнал всех выполненных команд с результатами

🔄 Откаты и повторные попытки

Система поддерживает откат выданных привилегий в случае ошибок или возвратов:

⚡ Производительность и кэширование

• Пул подключений — переиспользование TCP-соединений для снижения нагрузки
• Кэш результатов — сохранение результатов проверок статуса для быстрого доступа
• Асинхронное выполнение — команды выполняются параллельно на разных серверах
• Graceful degradation — при недоступности одного сервера система продолжает работу с остальными

🛡️ Безопасность

🔍 Диагностика проблем

💡 Советы по настройке

• Тестируйте на dev-сервере. Настройте тестовый сервер с primary: false для проверки команд перед продакшеном.
• Используйте переменные. В командах доступны: {nick} (ник игрока), {quantity} (количество), {item_id} (ID товара).
• Группируйте команды. Для одного товара можно указать несколько команд — они выполнятся последовательно.
• Мониторьте статус. Регулярно проверяйте статус серверов через админ-панель, настройте уведомления о сбоях.
• Балансируйте нагрузку. Если у вас высоконагруженный проект, распределите команды между несколькими серверами.

🌐 API Доставка товаров

Бот поддерживает выдачу товаров не только через RCON, но и через REST API запросы к вашему серверу.

api_delivery:
  enabled: true
  base_url: "https://your-server.com"
  bearer_token: "secret_token"
  delivery_endpoint: "/api/delivery"
  rollback_endpoint: "/api/rollback"
  timeout: 30

- id: my_item
  title: "Мой товар"
  price_usd: 10.0
  api_delivery_enabled: true  # ✅

📡 Формат 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}

🎯 Приоритет методов доставки

1. Собственная API конфигурация товара - если у товара есть api_delivery с enabled: true
2. Глобальная API конфигурация - если api_delivery_enabled: true у товара
3. RCON доставка - если API не настроен или отключен

🔧 Переопределение для отдельных товаров

Если нужны разные настройки для конкретного товара:

- id: special_item
  title: "Особый товар"
  price_usd: 50.0
  # Собственная конфигурация API
  api_delivery:
    enabled: true
    base_url: "https://special-api.com"
    bearer_token: "different_token"
    delivery_endpoint: "/api/vip/grant"
    rollback_endpoint: "/api/vip/revoke"
    timeout: 60

📚 Документация

📖 Подробная документация по 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

📊 Как работает

💡 Практические примеры

📈 Почему это работает

• Прозрачность. Люди видят, куда идут деньги и какой прогресс достигнут.
• Вовлечение. Визуализация прогресса мотивирует донатить.
• Социальное доказательство. Люди видят, что другие уже поддержали проект.
• Автоматизация. Не нужно вручную обновлять прогресс в соцсетях.

🤝 Рефералы и кешбек

Комплексная система лояльности для привлечения новых пользователей и стимулирования повторных покупок. Объединяет реферальную программу с бонусами за покупки.

🔗 Реферальная система

Позволяет пользователям приглашать друзей и получать бонусы с их покупок.

referral:
  enabled: true
  # Бонус для того, кто пригласил (USD)
  referrer_bonus: 1.0
  # Бонус для нового пользователя (USD)
  referee_bonus: 0.5
  # Минимальная сумма покупки для активации
  min_purchase_amount: 5.0
  # Только первая покупка реферала
  first_purchase_only: true

Управление через админ-панель

Доступ: /admin → «🤝 Реферальная система»

• Включение/выключение — переключатель активности программы
• Настройка бонусов — изменение размера вознаграждений
• Статистика — топ рефереров, количество приглашений, начисленные бонусы
• Сброс реферала — через /whois → пользователь → «Сброс реферала»

💰 Система кешбека

Автоматически начисляет бонусы на баланс пользователя с каждой покупки. Накопленный кешбек можно использовать для оплаты следующих покупок.

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 реферальный бонус.
• Минимальная сумма. Установите порог активации, чтобы избежать злоупотреблений мелкими покупками.
• Промо-кампании. Временно увеличивайте бонусы для привлечения пользователей на старте проекта.
• Контроль лимитов. Ограничьте максимальный баланс кешбека, чтобы пользователи не накапливали слишком много.

🏆 Таблица лидеров

Публичный рейтинг активных донатеров создаёт соревновательный эффект и мотивирует пользователей поддерживать проект. Отображается в боте, каналах и может быть интегрирована на сайт.

🎯 Как это работает

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%)

📊 Стратегии использования

💡 Советы по настройке

• Комбинируйте топы. Ведите и постоянный, и месячный топ одновременно — публикуйте их в разных каналах или постах.
• Минимальный порог. Установите минимальную сумму для попадания в топ (например, $10), чтобы избежать засорения тестовыми платежами.
• Конфиденциальность. Дайте пользователям возможность скрыться из топа через настройки профиля.
• Анонсы победителей. В конце месяца делайте пост с поздравлениями и вручением наград топ-3.
• Регулярность публикаций. Публикуйте обновлённый топ еженедельно в канале, чтобы поддерживать интерес.
• Визуализация. Используйте графики и диаграммы для отображения динамики топа.

📈 Почему это работает

• Социальное доказательство. Люди видят, что другие активно поддерживают проект.
• Соревнование. Желание попасть или остаться в топе мотивирует донатить больше.
• Признание. Публичная благодарность — сильный стимул для повторных донатов.
• Статус. Попадание в топ повышает статус в сообществе.
• FOMO эффект. Боязнь упустить возможность быть в числе лучших стимулирует активность.

💸 Компенсации и возвраты

Комплексная система возврата средств и отмены выданных товаров для решения конфликтных ситуаций и ошибок. Поддерживает автоматические возвраты платежей, откаты доставок и ручные компенсации.

💳 Возврат платежей

📦 Управление доставками

Отмена выданных товаров и откат 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 → «Кешбек»

🔄 Полный процесс возврата

Пошаговая инструкция для полного возврата покупки:

1. Найти покупку. Через /whois → пользователь → «Покупки» найти нужную транзакцию
2. Проверить доставку. Через /delivery_status delivery_id посмотреть статус выдачи товара
3. Откатить выдачу. Если товар был выдан — отменить через «Отменить выдачу» или /delivery_cancel
4. Вернуть деньги.
   • Telegram Stars: /refund_stars_by_id purchase_id
   • Другие провайдеры: вручную через админ-панель провайдера
5. Компенсация (опционально). Начислить бонус на кешбек-баланс через /whois
6. Уведомить пользователя. Написать сообщение с объяснением и извинениями

📊 Журналы и аудит

• Журнал доставок — история всех выдач с фильтрами по статусу, дате, пользователю
• Аудит админов — логирование всех операций возврата и отмены
• История кешбека — все начисления и списания для каждого пользователя
• Экспорт данных — выгрузка журналов в файл для анализа

💡 Советы и рекомендации

• Быстрота реакции. Обрабатывайте запросы на возврат в течение 24 часов — это критично для репутации.
• Проверяйте перед откатом. Всегда используйте /delivery_status чтобы убедиться, что товар действительно был выдан.
• Документируйте причины. В комментариях к операциям указывайте причину возврата для статистики.
• Сверхкомпенсация. Добавьте 5-10% сверху при возврате по вашей вине — это укрепляет лояльность.
• Автоматизация. Для Telegram Stars используйте быстрые команды — полный возврат за 10 секунд.
• Превентивные меры. Регулярно проверяйте логи RCON/API, чтобы предотвращать проблемы с доставкой.

🧰 Диагностика

• Бот не отвечает: проверьте BOT_TOKEN, удаление webhook при polling (логи при старте), папку logs/.
• Платежи не проходят: ключи и флаги провайдеров, доступность API, настройки в config.yml.
• Выдача на сервер не сработала: параметры rcon, онлайн сервера, логи RCON.