TKBK Studio
TKBK Studio
Претензии покупателей по артикулам — размер, качество, брак, упаковка — и что поправить в карточке
Сервис для селлера: выгружает отзывы с Wildberries (новые, с ответом и архив) и Ozon, если у магазина есть доступ к отзывам по API, и раскладывает претензии покупателей по категориям — размер, качество, брак, упаковка, доставка, цена.
По каждому артикулу видно, сколько отзывов с претензиями, какие категории лидируют и что именно пишут покупатели. Для самых проблемных товаров нейросеть через TKBK API подсказывает, что поправить в карточке (таблица размеров, описание, фото, комплектация) и что передать производству.
Отчёт собирается по расписанию, приходит сводкой в Telegram и открывается в браузере. Каждый отзыв размечается один раз, поэтому ежедневные прогоны стоят копейки.
Для кого: Селлеры и менеджеры маркетплейсов, отвечающие за карточки и качество товара
Ключи и токены не вводятся на сайте — их кладут в файл .env на своём сервере.
WB_TOKENТокен API Wildberries — ЛК → Настройки → Доступ к API → категория «Вопросы и отзывы», только чтениеOZON_CLIENT_IDClient-Id Ozon — Необязательно; отзывы — только с подпискойOZON_API_KEYAPI-ключ Ozon — ЛК Ozon → Настройки → API-ключиTKBK_API_KEYКлюч TKBK API — tkbk.online → API-ключиTELEGRAM_BOT_TOKENТокен Telegram-бота — @BotFather → /newbotTELEGRAM_CHAT_IDID чата для сводки — Добавьте бота в чатREPORT_PASSWORDПароль веб-интерфейса — Пусто — временный пароль в логе# Аналитика отзывов WB и Ozon — {{SHOP_NAME}}
Сервис выгружает отзывы покупателей с Wildberries (и Ozon, если доступно), раскладывает претензии по
категориям — размер, качество, брак, упаковка, доставка, цена — и собирает отчёт по артикулам: топ
претензий, цитаты и что поправить в карточке. Отчёт приходит в Telegram и открывается в браузере.
## Что умеет
- WB Feedbacks API: отзывы без ответа, с ответом и архив за последние {{ANALYSIS_DAYS}} дн.; подсказка WB
«маломерит/большемерит» и теги покупателя учитываются.
- Ozon `/v2/review/list` — если у магазина есть подписка «Управление отзывами» или Premium Pro; без неё
Ozon просто пропускается.
- Разметка нейросетью через TKBK API (модель `{{AI_MODEL}}`) пачками по 25 отзывов; каждый отзыв
размечается один раз (кэш в SQLite), отзывы только с оценкой не тратят запросы.
- Сводка по артикулам: отзывы, средняя оценка, претензии по категориям с долями и примерами.
- Для топ-{{TOP_ARTICLES}} артикулов — рекомендации: что поправить в карточке и что передать производству.
- HTML-отчёт (самодостаточный файл) + сводка в Telegram каждый день в {{REPORT_HOUR}}:00, запуск вручную кнопкой.
## Запуск за 5 минут
### С Docker
```bash
cp .env.example .env # WB_TOKEN, TKBK_API_KEY, по желанию Ozon и Telegram
docker compose up -d --build
```
Откройте http://localhost:8000 (логин `admin`, пароль из `REPORT_PASSWORD` или из лога) и нажмите
«Собрать отчёт сейчас». Первый прогон с большим числом отзывов займёт несколько минут.
### Без 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
```
## Где взять ключи
### Wildberries
1. ЛК продавца → **Настройки → Доступ к API** → «Создать токен», тип **Персональный**.
2. Категория **«Вопросы и отзывы»**, галочка **«Только на чтение»**.
3. Токен → `WB_TOKEN`.
### Ozon (необязательно)
1. ЛК → **Настройки → API-ключи** → ключ с ролью **Admin read only**.
2. `Client-Id` → `OZON_CLIENT_ID`, ключ → `OZON_API_KEY`.
3. Методы отзывов работают только с подпиской «Управление отзывами» или Premium Pro — без неё в логе будет
предупреждение, а отчёт соберётся по WB.
### TKBK API
tkbk.online → личный кабинет → **API-ключи** → `TKBK_API_KEY`.
### Telegram (необязательно)
Бот от @BotFather → `TELEGRAM_BOT_TOKEN`, чат → `TELEGRAM_CHAT_ID`. Чтобы в сообщении была ссылка на
отчёт, укажите `PUBLIC_URL` (адрес, по которому открывается сервис).
## Настройки из мастера
`app/config.py` (константы `WIZARD_*`): название магазина, период анализа, сколько артикулов разбирать,
час отчёта, модель. Переопределяются в `.env`: `SHOP_NAME`, `ANALYSIS_DAYS`, `TOP_ARTICLES`, `REPORT_HOUR`,
`TKBK_MODEL`. Категории претензий — `app/models.py`, подсказки нейросети — `app/classifier.py`.
## Тесты
```bash
pip install pytest==9.1.1
pytest
```
Тесты не ходят в сеть: WB, Ozon, TKBK API и Telegram подменены `httpx.MockTransport`.
## FAQ
**Сколько стоит разметка?** Пачка из 25 отзывов — один запрос к модели. 1000 новых отзывов ≈ 40 запросов
на разметку + по одному на рекомендации для каждого артикула из топа. Уже размеченные отзывы повторно не
отправляются. Лимит на прогон — `MAX_REVIEWS_PER_RUN`.
**WB отвечает 429.** Лимит категории «Вопросы и отзывы» — 3 запроса в секунду; сервис делает паузы и
повторяет запрос.
**Отчёт пустой.** Проверьте токен WB (нужна категория «Вопросы и отзывы») и период анализа. Логи:
`docker compose logs -f reviews`.
## Ограничения API
- WB: до 5000 отзывов за запрос и не больше 199 990 пропуска — для очень больших магазинов период лучше сократить.
- Архив WB не фильтруется по дате на стороне API — сервис листает до нужной даты сам.
- Ozon не отдаёт по API «достоинства» и «недостатки» — только текст и оценку.
- Рекомендации нейросети — подсказка, а не истина: проверяйте их перед правкой карточки.
Оценка 0–10 после заказа: довольных — на Яндекс Карты, 2ГИС и WB, недовольных — сразу к менеджеру
Название, описание и характеристики под правила каждой площадки — по одному товару или сотнями из CSV
Выручка, заказы, возвраты, остатки с прогнозом и юнит-экономика трёх маркетплейсов на одной странице