TKBK Studio
TKBK Studio
Новая сделка → нейросеть оценивает лид → примечание, тег «горячий/тёплый/холодный» и задача менеджеру
Сервис для отдела продаж на amoCRM: как только появляется новая сделка, он получает вебхук, собирает данные сделки, контакта и примечаний и просит нейросеть через TKBK API оценить лид — насколько клиент готов купить и что делать дальше.
В сделке появляются примечание с оценкой и причиной, тег температуры и задача «Звонок» ответственному со сроком, зависящим от температуры. Менеджеры начинают день с горячих лидов, а не с очереди по времени.
Телефоны и почты клиентов не уходят в нейросеть, повторные вебхуки не создают дублей, а критерии идеального клиента задаются обычным текстом в мастере.
Для кого: Отделы продаж и РОПы на amoCRM, интеграторы
Ключи и токены не вводятся на сайте — их кладут в файл .env на своём сервере.
AMOCRM_DOMAINАдрес аккаунта amoCRM — company.amocrm.ruAMOCRM_TOKENДолгосрочный токен amoCRM — Настройки → Интеграции → своя интеграция → Ключи и доступыWEBHOOK_SECRETСекрет в адресе вебхука — Длинная случайная строкаTKBK_API_KEYКлюч TKBK API — tkbk.online → API-ключиADMIN_TOKENТокен для ручного запуска оценки — Необязательно# AI-квалификация лидов в amoCRM
Новая сделка в amoCRM → вебхук → сервис собирает данные сделки, контакта и примечаний → нейросеть
(TKBK API, модель `{{AI_MODEL}}`) оценивает лид → в сделке появляются примечание с оценкой, тег
«{{TAG_HOT}}» / «{{TAG_WARM}}» / «{{TAG_COLD}}» и задача ответственному менеджеру.
## Что умеет
- Принимает вебхук amoCRM «Сделка добавлена» (и по желанию «Сделка изменила статус»).
- Оценка: горячий / тёплый / холодный, балл 0–100, причина и конкретный следующий шаг.
- Примечание в сделку, тег температуры (старые теги температуры снимаются, остальные не трогаются).
- Задача «Звонок» ответственному со сроком: горячий — {{TASK_HOURS_HOT}} ч, тёплый — {{TASK_HOURS_WARM}} ч, холодный — {{TASK_HOURS_COLD}} ч.
- Защита от повторов: одну сделку не оценивает чаще раза в `REQUALIFY_HOURS` часов.
- Персональные данные не уходят в нейросеть: вместо телефона и почты — «телефон есть» и домен почты.
- Ручной запуск по API для любой сделки, повтор запросов при лимитах amoCRM и TKBK.
## Запуск за 5 минут
### С Docker
```bash
cp .env.example .env # заполните AMOCRM_DOMAIN, AMOCRM_TOKEN, WEBHOOK_SECRET, TKBK_API_KEY
docker compose up -d --build
curl http://localhost:8000/health
```
### Без 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
```
amoCRM должен достучаться до сервиса по HTTPS: разместите его на сервере с доменом (nginx/Caddy
с сертификатом) или для теста пробросьте порт через туннель (например, `cloudflared tunnel --url http://localhost:8000`).
## Настройка amoCRM пошагово
### 1. Долгосрочный токен
1. amoCRM → **Настройки → Интеграции** → «Создать интеграцию» → **внешняя интеграция**.
2. Отметьте доступ **«Доступ к данным аккаунта»** (сделки, контакты, задачи, примечания) и сохраните.
3. В интеграции откройте вкладку **«Ключи и доступы»** → **«Долгосрочные токены»** → «Сгенерировать
токен», выберите срок действия.
4. Токен → `AMOCRM_TOKEN`, адрес аккаунта (`company.amocrm.ru`) → `AMOCRM_DOMAIN`.
Токен действует от имени пользователя, который его выпустил, — у него должны быть права на редактирование
сделок и создание задач.
### 2. Вебхук
1. Придумайте секрет и впишите в `WEBHOOK_SECRET`.
2. amoCRM → **Настройки → Интеграции → Web hooks** → «Добавить хук».
3. Адрес: `https://ваш-домен/amocrm/webhook/<WEBHOOK_SECRET>`.
4. События: **«Сделка добавлена»** (и **«Сделка изменила статус»**, если включите `QUALIFY_ON_STATUS=true`).
### 3. Ключ TKBK API
tkbk.online → личный кабинет → **API-ключи** → «Создать» → `TKBK_API_KEY`.
## Ручной запуск
```bash
curl -X POST http://localhost:8000/api/leads/12345/qualify -H "Authorization: Bearer <ADMIN_TOKEN>"
```
Оценивает сделку сразу, даже если её недавно уже оценивали.
## Настройки из мастера
`app/config.py` (константы `WIZARD_*`): описание компании и идеального клиента, модель, названия тегов, сроки
задач. Переопределяются в `.env`: `COMPANY_CONTEXT`, `TKBK_MODEL`, `TAG_HOT`, `TAG_WARM`, `TAG_COLD`,
`TASK_HOURS_HOT`, `TASK_HOURS_WARM`, `TASK_HOURS_COLD`. Чем подробнее описан идеальный клиент, тем точнее оценка.
## Тесты
```bash
pip install pytest==9.1.1
pytest
```
Тесты не ходят в сеть: amoCRM и TKBK API подменены `httpx.MockTransport`.
## FAQ
**Вебхук не приходит.** Проверьте, что адрес открывается снаружи по HTTPS и секрет совпадает (при
неверном секрете сервис отвечает 404). Логи: `docker compose logs -f qualifier`.
**Ошибка 401 от amoCRM.** Токен истёк или отозван — выпустите новый в интеграции.
**Почему не все поля сделки видны нейросети?** Отправляются только непустые поля, кроме телефонов и почт
(до 25 полей) и последние 20 примечаний. Лимиты — в `app/qualifier.py`.
**Можно ли вместо задачи двигать сделку по этапам?** Да — добавьте `PATCH /api/v4/leads/{id}` со
`status_id` в `app/amocrm.py` (см. идеи ниже).
## Ограничения API
- amoCRM: до 7 запросов в секунду на интеграцию — сервис обрабатывает не больше 2 сделок одновременно и
повторяет запрос при 429.
- Вебхуки amoCRM не подписываются — защита держится на секрете в адресе; держите его в тайне.
- amoCRM ждёт ответ на вебхук несколько секунд — оценка идёт в фоне, ответ уходит сразу.
Вопросы с кнопками, расчёт цены по формуле, телефон клиента — заявка менеджеру, в CSV и CRM
Название, описание и характеристики под правила каждой площадки — по одному товару или сотнями из CSV
Претензии покупателей по артикулам — размер, качество, брак, упаковка — и что поправить в карточке