TKBK Studio
TKBK Studio
Каталог с фото, корзина, оформление заказа и оплата картой или звёздами прямо в Telegram
Готовый магазин для тех, кто продаёт через Telegram: кофейни и пекарни, мастерские, локальные бренды, продавцы цифровых товаров. Покупатель листает каталог с фото, собирает корзину, оставляет контакты и оплачивает заказ, не выходя из мессенджера.
Оплата — встроенные платежи Telegram: картой через ЮKassa, Telegram Stars или «при получении». Каждый заказ приходит вам в личку или в группу менеджеров с кнопками статусов, а покупатель сразу узнаёт, что заказ собирают или отправили.
В отличие от конструкторов, это ваш код без абонентской платы: товары в простом файле products.json, данные в SQLite на вашем сервере, запуск одной командой в Docker. Внутри — выгрузка заказов в Excel, рассылка по покупателям и тесты на расчёт корзины.
Для кого: Небольшие магазины, кофейни, мастерские, продавцы цифровых товаров
Ключи и токены не вводятся на сайте — их кладут в файл .env на своём сервере.
BOT_TOKENТокен бота — @BotFather → /newbotADMIN_CHAT_IDЧат для заказов — Ваш ID у @userinfobot или ID группы (отправьте боту /id в группе)PAYMENTS_PROVIDER_TOKENТокен ЮKassa — @BotFather → /mybots → бот → Payments → ЮKassa. Только для оплаты картойADMIN_IDSДополнительные администраторы — ID через запятую# {{BRAND}} — бот-магазин в Telegram
Готовый магазин внутри Telegram: каталог с фото, корзина, оформление заказа
и оплата картой (ЮKassa) или Telegram Stars. Заказы приходят вам в личку
или в группу менеджеров, статусы меняются одной кнопкой.
## Что умеет
- **Каталог** из файла `products.json`: категории → товары с фото, описанием и ценой, листание страниц.
- **Корзина** хранится в базе — не теряется после перезапуска бота; кнопки ➖/➕/✖.
- **Оформление заказа**: имя → телефон (кнопкой «Отправить номер» или текстом) → адрес → подтверждение.
- **Оплата** встроенными платежами Telegram:
`card` — картой через ЮKassa, `stars` — Telegram Stars, `none` — при получении (заказ сразу уходит менеджеру).
- **Доставка**: платная, бесплатная от суммы, минимальная сумма заказа (для рублей).
- **Уведомление администратору** о каждом заказе с кнопками статусов: «Собираем» → «Отправлен» → «Выполнен» / «Отменить».
Покупатель получает сообщение о каждом изменении. При отмене оплаченного звёздами заказа звёзды возвращаются автоматически.
- **Команды администратора**: `/orders`, `/order 12`, `/export` (CSV для Excel), `/broadcast` (рассылка).
- **«Мои заказы»** у покупателя: статусы, повторная оплата и отмена неоплаченного заказа.
## Запуск за 5 минут
### 1. Получите токены
| Что | Где взять |
|---|---|
| `BOT_TOKEN` | [@BotFather](https://t.me/BotFather) → `/newbot` → придумайте имя и юзернейм → скопируйте токен |
| `ADMIN_CHAT_ID` | Ваш ID — напишите [@userinfobot](https://t.me/userinfobot). Для группы менеджеров: добавьте бота в группу и отправьте `/id` |
| `PAYMENTS_PROVIDER_TOKEN` | @BotFather → `/mybots` → ваш бот → **Payments** → **ЮKassa** → для начала «Connect ЮKassa Test». Нужен только для оплаты картой |
Скопируйте `.env.example` в `.env` и впишите значения.
### 2а. Запуск в Docker (рекомендуется для сервера)
```bash
docker compose up -d --build
docker compose logs -f # смотреть логи
```
### 2б. Запуск без Docker (Python 3.12+)
```bash
python -m venv .venv
# Windows: .venv\Scripts\activate Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python -m app
```
Откройте бота в Telegram и нажмите **Старт**. Готово!
## Настройка
- **Товары** — `products.json`:
```json
{"id": "brazil-250", "title": "Бразилия, 250 г", "description": "…",
"price": 690, "price_stars": 350, "photo": "https://…/photo.jpg", "available": true}
```
`id` — латиница, цифры, `-` и `_` (до 32 символов, не меняйте у существующих товаров);
`price` — цена в рублях (можно с копейками), `price_stars` — цена в звёздах (нужна только при оплате звёздами);
`photo` — ссылка на картинку или `file_id` (пришлите боту фото из чата администратора — он ответит `file_id`);
`"available": false` — скрыть товар. После правок перезапустите бота
(`docker compose up -d --build` или заново `python -m app`).
- **Тексты, доставка, способ оплаты** — в начале `app/config.py` (значения из мастера TKBK Studio).
Способ оплаты можно переключить без правки кода: `PAYMENT_METHOD=card|stars|none` в `.env`.
- **Несколько менеджеров** — создайте группу, добавьте туда бота, отправьте в группе `/id` и укажите этот ID в `ADMIN_CHAT_ID`.
## Команды
| Команда | Кто | Что делает |
|---|---|---|
| `/start`, `/catalog`, `/cart`, `/orders`, `/help` | все | меню, каталог, корзина, мои заказы, справка |
| `/paysupport` | все | вопрос по оплате — уходит менеджеру (Telegram требует эту команду у ботов с оплатой) |
| `/orders [статус]` | админ | последние заказы, например `/orders paid` |
| `/order 12` | админ | заказ с кнопками статусов |
| `/export` | админ | все заказы файлом CSV (открывается в Excel) |
| `/broadcast` | админ | ответьте этой командой на любое сообщение — бот разошлёт его всем покупателям |
| `/id` | все | ID текущего чата |
## Проверка
```bash
pip install -r requirements.txt pytest==9.1.1
pytest
```
Тесты проверяют расчёт корзины и доставки, `products.json`, телефоны, статусы и выгрузку CSV.
## Структура
```
app/
__main__.py запуск бота
config.py настройки: .env + значения из мастера
catalog.py загрузка и проверка products.json
cart.py деньги: суммы в копейках/звёздах, доставка, итоги
orders.py заказы: статусы, телефоны, CSV
db.py SQLite: покупатели, корзины, заказы
shop.py меню, каталог, корзина, «Мои заказы»
checkout.py оформление и оплата
admin.py команды и кнопки администратора
views.py тексты сообщений
keyboards.py кнопки
products.json каталог
```
## FAQ
**Бот не присылает заказы администратору.** Проверьте `ADMIN_CHAT_ID` и что вы хотя бы раз нажали «Старт» у бота
(бот не может писать первым). Для группы — бот должен быть её участником.
**Счёт не выставляется.** Проверьте `PAYMENTS_PROVIDER_TOKEN` и сумму: у Telegram есть минимальная сумма платежа
(около 1 $ в пересчёте на рубли). Ошибка приходит в чат администратора.
**Как перейти с тестовых платежей на настоящие?** В @BotFather → Payments подключите боевую ЮKassa и замените токен в `.env`.
**Карта или звёзды?** По правилам Telegram цифровые товары и услуги внутри Telegram продают за Stars,
а физические товары — через платёжных провайдеров (ЮKassa). Выберите способ, подходящий вашему бизнесу.
**Нужны чеки по 54-ФЗ?** Подключите отправку чеков в личном кабинете ЮKassa или передавайте данные чека
в `provider_data` счёта (`send_invoice` в `app/checkout.py`) по документации ЮKassa для Telegram.
**Где хранятся данные?** В SQLite: `data/shop.db` (в Docker — том `shop-data`). Делайте резервные копии этого файла.
**Можно ли запустить несколько копий бота?** Нет — один токен = один запущенный экземпляр, иначе Telegram вернёт ошибку Conflict.
Услуги, мастера, свободные окна на 14 дней, напоминания за сутки и за 2 часа, предоплата и отзывы
Оценка 0–10 после заказа: довольных — на Яндекс Карты, 2ГИС и WB, недовольных — сразу к менеджеру
Оплата звёздами или картой, одноразовые ссылки, напоминания о продлении и автоисключение по окончании