TKBK Studio
TKBK Studio
Проверенные через API уведомления об оплатах и возвратах в Telegram, журнал, ежедневная сверка и CSV
Сервис для владельца интернет-магазина или онлайн-школы на ЮKassa: принимает HTTP-уведомления об оплатах, отменах и возвратах, но не доверяет их телу — каждый раз проверяет платёж запросом к API ЮKassa и только потом пишет его в журнал и отправляет сообщение в Telegram.
Раз в день сервис сверяет журнал с ЮKassa: всё, что пришло в API за вчера, попадает в базу, а потерянные уведомления видны в сводке. В сводке — оплаты, сумма к зачислению после комиссии, отмены с главной причиной и возвраты.
Панель под паролем показывает последние платежи и журнал уведомлений, а выгрузка CSV за любой период открывается в Excel без настроек.
Для кого: Интернет-магазины, онлайн-школы и сервисы, принимающие оплату через ЮKassa
Ключи и токены не вводятся на сайте — их кладут в файл .env на своём сервере.
YOOKASSA_SHOP_IDshopId ЮKassa — Личный кабинет → Интеграция → Ключи APIYOOKASSA_SECRET_KEYСекретный ключ ЮKassa — Личный кабинет → Интеграция → Ключи API → Выпустить ключTELEGRAM_BOT_TOKENТокен Telegram-бота — @BotFather → /newbotTELEGRAM_CHAT_IDID чата для уведомлений — Добавьте бота в чатADMIN_PASSWORDПароль панели — Пусто — временный пароль выводится в лог# Мониторинг платежей ЮKassa — {{SHOP_NAME}}
Сервис принимает HTTP-уведомления ЮKassa (`payment.succeeded`, `payment.canceled`, `refund.succeeded`),
**не доверяет телу уведомления** — каждый раз запрашивает платёж или возврат через API
(`GET /v3/payments/{id}`, `GET /v3/refunds/{id}`), пишет его в журнал SQLite и присылает сообщение в
Telegram. Раз в день сверяет журнал с ЮKassa и присылает сводку.
## Что умеет
- Приём уведомлений с проверкой адреса отправителя (сети ЮKassa) и подтверждением статуса через API.
- Журнал платежей, возвратов и всех полученных уведомлений с отметкой «подтверждено / нет».
- Сообщения в Telegram: оплата (крупная — от {{BIG_PAYMENT_RUB}} ₽ — выделяется), отмена с понятной причиной, возврат.
- Ежедневная сверка в {{REPORT_HOUR}}:05: всё, что есть в ЮKassa за вчера, попадает в журнал; потерянные
уведомления видны в сводке.
- Сводка: оплачено, к зачислению после комиссии, отмены и главная причина, возвраты, итог дня.
- Панель с последними платежами и журналом уведомлений, выгрузка CSV за любой период (под паролем).
- Если API ЮKassa недоступен, сервис отвечает 503 — ЮKassa повторит уведомление позже, ничего не теряется.
## Запуск за 5 минут
### С Docker
```bash
cp .env.example .env # shopId, секретный ключ, Telegram, ADMIN_PASSWORD
docker compose up -d --build
```
Панель: http://localhost:8000 (логин `admin`). Адрес для уведомлений: `https://ваш-домен/yookassa/webhook`.
### Без Docker (Python 3.12)
```bash
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
python -m app
```
ЮKassa шлёт уведомления только на HTTPS-адрес. Поставьте сервис за nginx или Caddy с сертификатом и
включите `TRUST_PROXY=yes`, чтобы проверка IP видела настоящий адрес ЮKassa.
## Настройка ЮKassa пошагово
1. Личный кабинет ЮKassa → **Интеграция → Ключи API**. Скопируйте **shopId** → `YOOKASSA_SHOP_ID` и
выпустите **секретный ключ** → `YOOKASSA_SECRET_KEY`. Для проверки можно взять тестовый магазин и ключ `test_…`.
2. **Интеграция → HTTP-уведомления**: укажите `https://ваш-домен/yookassa/webhook` и отметьте события
`payment.succeeded`, `payment.canceled`, `refund.succeeded` (можно и `payment.waiting_for_capture`).
3. Сохраните. Сделайте тестовый платёж — в Telegram придёт сообщение, в панели появится запись.
Ключ нужен только для чтения платежей: сервис ничего не создаёт и не списывает.
## Telegram
1. [@BotFather](https://t.me/BotFather) → `/newbot` → `TELEGRAM_BOT_TOKEN`.
2. Добавьте бота в чат и укажите его ID в `TELEGRAM_CHAT_ID` (узнать можно у @getmyid_bot).
## Ручные действия
```bash
# Сверка за конкретный день
curl -u admin:ПАРОЛЬ -X POST "http://localhost:8000/reconcile?day=2026-10-09"
# Выгрузка CSV (разделитель «;», открывается в Excel)
curl -u admin:ПАРОЛЬ -o payments.csv "http://localhost:8000/export.csv?date_from=2026-10-01&date_to=2026-10-31"
```
## Настройки из мастера
`app/config.py` (константы `WIZARD_*`): название магазина, час сводки, порог крупной оплаты, проверка IP.
Переопределяются в `.env`: `SHOP_NAME`, `REPORT_HOUR`, `BIG_PAYMENT_RUB`, `CHECK_IP`.
## Тесты
```bash
pip install pytest==9.1.1
pytest
```
Тесты не ходят в сеть: API ЮKassa и Telegram подменены `httpx.MockTransport`.
## FAQ
**В журнале «НЕ подтверждено».** Статус в API не совпал с событием: уведомление поддельное или устарело
(например, платёж уже вернули). Сообщение в Telegram в этом случае не отправляется.
**Уведомления отклоняются с 403.** Сервис стоит за прокси, а `TRUST_PROXY=no`, или Docker подменяет адрес
отправителя. Включите `TRUST_PROXY=yes` (за nginx/Caddy) либо `CHECK_IP=no` — главная защита всё равно
проверка через API.
**Почему суммы в сводке не совпадают с выпиской?** Сводка считает по дате создания платежа в часовом поясе
`TIMEZONE`, а зачисления на счёт идут по реестрам ЮKassa на следующий рабочий день.
## Ограничения API
- Список платежей ЮKassa отдаёт до 100 объектов за запрос — сервис листает курсором.
- При превышении лимитов ЮKassa отвечает 429 — запрос повторяется с паузой.
- Тестовые платежи (`test: true`) пишутся в журнал, но не входят в сводку.
Услуги, мастера, свободные окна на 14 дней, напоминания за сутки и за 2 часа, предоплата и отзывы
Оценка 0–10 после заказа: довольных — на Яндекс Карты, 2ГИС и WB, недовольных — сразу к менеджеру
Оплата звёздами или картой, одноразовые ссылки, напоминания о продлении и автоисключение по окончании