Starvell Bot

Telegram-бот для продавцов на маркетплейсе Starvell: уведомления о заказах и чатах, автобамп лотов, возвраты, автовыдача и расширяемость через плагины. Интерфейс на aiogram 3, работа с сайтом через aiohttp, локальная БД пользователей — SQLite (tg_bot_exfa/bot.sqlite3).

---

Контакты

• Разработчик: @exfador
• Канал: @starvellapi
• Чат сообщества: @community_starvell
• Баги и вопросы: пишите в чат сообщества

---

Возможности

• Автобамп — подъём объявлений по расписанию мониторинга
• Заказы — уведомления о новых продажах, открытие заказа в браузере, возврат средств из Telegram
• Чаты Starvell — уведомления о новых сообщениях от покупателей, ответ текстом или фото, быстрые шаблоны ответов
• Уведомления — отдельные переключатели: авторизация на сайте, бамп, чаты, заказы
• Автовыдача — привязка товаров к выдаваемым кодам/контенту при продаже
• Шаблоны сообщений — сохранение и вставка заготовок при переписке
• Приветствие — настраиваемый текст и кулдаун для приветствия новым участникам (в конфиге)
• Префикс / водяной знак — префикс к исходящим сообщениям на Starvell (WATERMARK_ON, WATERMARK_TEXT)
• Плагины — загрузка Python-модулей из каталога plugins/, состояние в storage/plugins/, регистрация slash-команд
• Статистика — сводка по активности в боте
• Безопасность доступа к боту — пароль (хранится как MD5), до 5 попыток, блокировка на 24 ч; опциональные уведомления владельцу об успешном/неудачном входе
• Служебные команды: /start, /restart (перезапуск процесса), /update (проверка тегов на GitHub), /logs (ZIP архива папки logs/)
• Языки интерфейса: русский и английский
• Проверка версии — фоновый опрос и уведомление о доступных обновлениях (сверка с репозиторием на GitHub)

---

Стек

Компонент	Версия / заметка
Python	рекомендуется 3.11+
aiogram	3.18
aiohttp	≥ 3.9
aiosqlite	≥ 0.19
pydantic	2.x

Зависимости: requirements.txt.

---

Конфигурация

Файл: config/osnova.json (создаётся при первом запуске частично автоматически).

Основные поля:

Поле	Описание
BOT_TOKEN	токен от @BotFather
BOT_PASSWORD / BOT_PASSWORD_MD5	пароль для входа в бот (можно задать открытый пароль — будет сохранён как MD5)
SESSION_COOKIE	cookie-сессия авторизованного аккаунта Starvell (как в браузере)
DEFAULT_LANGUAGE	ru или en
DEBUG	подробные логи
WATERMARK_ON, WATERMARK_TEXT	водяной знак к исходящим сообщениям
WELCOME_*	приветствие: вкл/выкл, текст, кулдаун в минутах

Переменные окружения (перекрывают JSON при наличии): BOT_TOKEN, BOT_PASSWORD, BOT_PASSWORD_MD5, AUTHOR_USERNAME, CHANNEL_URL, CHAT_URL.

---

Установка на Windows

1. Установите Python 3.11 (или новее): python.org
   При установке включите Add Python to PATH.

2. Один раз установите зависимости: запустите setup_bot.bat.

3. Запуск: start_bot.bat (в корне проекта выполняется python run_bot.py).

4. При первом запуске введите BOT_TOKEN, пароль бота, при необходимости SESSION_COOKIE, выберите язык. Дальнейшие правки сессии, пароля и токена доступны из меню бота (Настройки).

---

Установка на Linux (Ubuntu / Debian)

Скрипт из репозитория API (как в оригинальной инструкции):

wget -O setup_starvell.sh https://raw.githubusercontent.com/exfador/starvell_api/refs/heads/main/setup_starvell.sh
chmod +x setup_starvell.sh
sudo ./setup_starvell.sh

После установки запустите бота так, как указано в выводе скрипта (или из каталога проекта):

python3 run_bot.py

Плагины

• Каталог по умолчанию: plugins/ в корне проекта.
• Состояние (отключённые плагины): storage/plugins/state.json.
• Управление: пункт «Плагины» в главном меню бота.

---

Ответственность

Использование бота должно соответствовать правилам Starvell и Telegram. Автор и сообщество не несут ответственности за действия пользователей и возможные ограничения со стороны платформ.