---
компонент: Чешуйка «CRM» — зеркало Bitrix24
статус: черновик v1
обновлено: 2026-08-28
решения: рабочий срез + активные воронки · двусторонняя синхронизация, Б24 главный
портал: bot-marketing.bitrix24.ru
связано: [[chesuyka]] — общие правила · [[master-app]] — плитка в мастере
---

# Чешуйка «CRM»

Зеркало нашего Bitrix24 внутри Кобры: у чата с клиентом всегда видно, кто он и где его сделка,
а то, что выяснилось в переписке, уезжает обратно в CRM.

## Шаг 1. Боль

Оператор переписывается с клиентом в Кобре, а всё, что о клиенте известно, лежит в Б24. Чтобы
узнать стадию сделки, ответственного или сумму — надо выйти из переписки, найти карточку, вернуться.
Обратно ничего не едет: договорённости из чата остаются в чате.

Уже случалось: у Motorland панель карточки клиента искала человека **только по «ИД на Авито»** и
находила 7 из 17, тогда как телефон давал 17 из 17 (#87791). Ту же ошибку легко повторить.

| Кому больно | Что должно случиться | Кто пользуется |
|---|---|---|
| аккаунт, продавец | у чата видно клиента, его сделки и следующий шаг | отдел продаж, руководитель |
| руководитель | видно картину по воронке, не заходя в Б24 | владелец |
| агенты | Алина знает контекст сделки и может двигать её сама | G005, S-серия |

## Что реально лежит в нашем Б24

Разведка 28.08.2026, живые цифры портала:

| Сущность | Записей |
|---|---|
| Сделки | 9 654 |
| Контакты | 10 147 |
| Лиды | 8 963 |
| Компании | 1 069 |
| Полей у сделки | 243, из них **187 пользовательских** |

### Воронки: какие живые

| ID | Воронка | Всего | За 2026 | Берём |
|---|---|---|---|---|
| 29 | Смарт-Заявки (Сделки) | 1 503 | **133** | да |
| 23 | Подписка (Основное) | 2 459 | **89** | да |
| 0 | Основное (Проекты) | 1 049 | **88** | да |
| 25 | `[old]` Решение | 4 208 | **68** | да — см. ниже |
| 35 | Партнеры | 182 | 11 | да |
| 15 | `[old]` Разработка | 242 | 2 | только чтение истории |
| 11 | `[old]` Внешние приложения | 7 | 0 | нет |
| 27 | `[old]` (VIP) Внешние приложения | 4 | 0 | нет |

⚠️ **Находка: воронка 25 помечена `[old]`, но живая** — 68 сделок за 2026 год, больше чем
у «Партнеров». Либо пометка устарела, либо туда что-то падает автоматикой мимо процесса.
Это вопрос к отделу продаж **до** начала работы: если синхронизировать по пометке в названии,
68 сделок года выпадут молча.

### Стадии активных воронок

- **29 · Смарт-Заявки:** Биржа сделок → Сбор треб. запланирован → Сбор треб. проведен →
  КП/презентация отправлено → Согласована настройка → Создано демо/сториз → Получено согласие
  об оплате → Оплата получена → Произведена установка → Расчет получен → Работа завершена ·
  Не реализовано
- **23 · Подписка:** Новый → Подключение → Ждем оплату → Активен → Отключен → Успешна ·
  Провалена · Анализ причины провала · Временно отключился
- **0 · Проекты:** Биржа проектов → Встреча запланирована → Встреча проведена → КП отправлено →
  Стоимость согласована → Оплата получена → Разработка завершена → Установка завершена →
  Выставлен счет → Переход на абонентскую → Завершена · Провалена
- **35 · Партнеры:** Биржа партнеров → Партнер закреплен → 1-ое касание → 2-ое касание →
  Встреча запланирована → Встреча проведена → Доступ обучение/триал → Обучение проведено →
  Договор отправлен → Договор подписан → Первый лид/оплата · Провалена

Стадии **не хардкодить**: читать `crm.status.list` и складывать в свою таблицу. Продажи их меняют.

---

## Шаг 2. Рабочий срез полей

Из 187 пользовательских полей на 300 свежих сделках **заполнено хотя бы раз — 107, ни разу — 80**.
Берём то, что заполняется чаще 5%, и режем дальше по смыслу.

⚠️ **Ловушка API:** `crm.deal.userfield.list` возвращает **пустые метки у всех 187 полей**.
Человекочитаемые названия отдаёт только `crm.deal.userfield.get` — по одному полю за вызов.
Значит справочник полей собирается **один раз батчами по 50** и кладётся к себе, иначе имена
полей в интерфейсе останутся кодами вида `UF_CRM_1544053195671`.

### Ядро среза — берём

| Доля | Поле | Что это | Тип |
|---|---|---|---|
| 100% | `UF_CRM_1544095238278` | Проект | список |
| 45% | `UF_CRM_6744265B1A7C9` | Тип Лида | список |
| 45% | `UF_CRM_1721656854460` | Ответственный лид-менеджер | список |
| 40% | `UF_CRM_67F8EAB5CDC83` | Тип обращения | список |
| 38% | `UF_CRM_1731050245271` | Тип клиента (новый / текущий) | список |
| 37% | `UF_CRM_1724402505378` | Ответственный менеджер | список |
| 20% | `UF_CRM_1721309745764` | Причины отмены | список |
| 17% | `UF_CRM_1721309779626` | Детализация причины отмены | текст |
| 17% | `UF_CRM_1587102730902` | Период оплаты | список |
| 16% | `UF_CRM_1606474600581` | Как платит | список |
| 11% | `UF_CRM_67CFEB06AA94F` | Особо важный клиент | да/нет |
| 10% | `UF_CRM_66C740052E03C` | MQL | список |
| 7% | `UF_CRM_690B21A29EF82` | Тип проекта | список |

### Даты процесса — берём, это воронка в полях

`Дата - Биржа сделок` · `Дата - 1-ое касание` · `Дата - 2-ое касание` ·
`Дата - Сбор требований запланирован` / `проведен` · `Дата - КП отправлено` ·
`Дата - Согласована настройка` · `Дата - создано демо` · `Дата - начало проекта` ·
`Дата - Не реализовано` · `Дата завершения профилирования лида`

По ним строится реальная длительность этапов — то, чего в стадиях не видно.

### Ссылки — берём

`Диалог в Web` (32%) · `Ссылка на чат` (16%) · `Ссылка на КП в Google диске` (14%) ·
`[Notion] Ссылка на описание проекта` (7%) · `Ссылка на аккаунт в админке` (7%) ·
`Ссылка в зум для сбора требований` (39%)

### Анкета брифа — берём только в карточку, не в списки

Восемь полей блока `UF_CRM_6687E088*` («Чем занимается компания», «Какую задачу решить»,
«Какая CRM используется», «Куда подключены мессенджеры», «Когда готовы заказывать»…) заполнены
у 42–44% и полезны при разговоре, но в списках и фильтрах не нужны.

### Не берём

80 полей, ни разу не заполненных в свежих сделках, и всё, что ниже 5%. Это не потеря данных:
чешуйка их **не показывает**, но и не портит — они остаются в Б24 нетронутыми.

**Правило:** срез — это настройка (SSI), а не константа в коде. Появилось новое поле — добавили
строку в сопоставление, не трогая релиз.

---

## Шаг 3. Своя сущность и буфер

Синхронизация **двусторонняя, Б24 главный**. Сквозных вызовов чужого API из интерфейса нет —
экран всегда открывается на своей копии.

```
интерфейс / агент → сущность чешуйки → очередь изменений → Bitrix24
                          ↑                                    │
                          └────── события + ночная сверка ──────┘
```

### Модель

| Наша сущность | Источник | Ключ |
|---|---|---|
| `client` | контакт + компания Б24 | `b24_contact_id`, `b24_company_id` |
| `deal` | сделка | `b24_deal_id` |
| `stage` | справочник стадий | `status_id` + `category_id` |
| `field_map` | справочник полей среза | `uf_code` |
| `link_chat` | связь чата Кобры с клиентом | `chat_id` ↔ `client` |

У каждой записи: `b24_modified_at`, `local_modified_at`, `synced_at`, `dirty`.

### Сопоставление клиента — каскад, а не один ключ

Прямая наука из #87791:

1. `crmClientId` из «своих полей» чата — если уже записан, доверяем ему;
2. **телефон** — нормализованный (`8XXXXXXXXXX` → `+7XXXXXXXXXX`, убрать пробелы, скобки, дефисы);
3. `avito_id`;
4. email;
5. имя — только как подсказка оператору, автоматически не связываем.

Нашли — **записываем `crmClientId` в свойства чата**, чтобы следующий раз шёл по первому шагу.

### Конфликты

Победитель — Б24, но с оговорками:

| Случай | Что делаем |
|---|---|
| Изменено только у нас | досылаем в Б24 |
| Изменено только в Б24 | принимаем |
| Изменено с обеих сторон | **выигрывает Б24**, наше пишем в лог и показываем оператору плашку «ваша правка не применилась» |
| Сделка удалена в Б24 | помечаем `archived`, не удаляем — иначе потеряем связь с чатом |

Молча терять правку нельзя: человек должен узнать, что его изменение не доехало.

### Очередь

- операции **идемпотентны**: повторная досылка не создаёт дубль (ключ операции = сущность + поле + версия);
- повторы с нарастающей паузой; после N неудач — в «мёртвые» с причиной и лицом ответственного;
- у оператора видно: «N изменений ждут отправки»;
- порядок операций по одной сделке сохраняется.

### Как узнаём об изменениях в Б24

Три механизма вместе, каждый закрывает дыру другого:

1. **События** `ONCRMDEALADD` / `ONCRMDEALUPDATE` / `ONCRMDEALDELETE` и аналоги по контактам —
   быстро, но теряются, если наш сервер лежал.
2. **Периодическая доборка** по `DATE_MODIFY > последняя сверка` — каждые 5–15 минут; чинит
   пропуски событий.
3. **Ночная полная сверка** — раз в сутки по идентификаторам, ищет расхождения и удалённое.

Первичная загрузка 9 654 сделок — постранично **по ID** (`filter[>ID]`), а не по `start`:
на больших смещениях постраничность по `start` в Б24 деградирует и начинает пропускать записи.

### Ограничения портала, которые надо заложить

- лимит около **2 запросов в секунду** — все чтения через `batch` (до 50 команд за вызов);
- полная выгрузка сделок ≈ 194 страницы по 50 — считать в минутах, а не секундах;
- **доступ к порталу с наших машин работает только через прокси** — прямое соединение падает
  на TLS. Для сервера чешуйки это отдельный пункт развёртывания, а не мелочь.

---

## Шаг 4. Экраны

По мерке — три на поверхность.

**Доковый вебапп (у чата, главный дом):**
1. **Карточка клиента** — кто это, компания, телефон, активные сделки, стадия, ответственный,
   следующий шаг. Кнопка «вставить в ответ» для реквизитов и ссылок.
2. **Сделка** — стадия и её история по датам процесса, сумма, поля среза, ссылки (КП, Notion, админка).
3. **Быстрое действие** — сменить стадию, поставить дату следующего шага, дописать причину отмены.

**Страница-артефакт в папке проекта:** воронка целиком — где сделки стоят, сколько висят на этапе,
что не двигалось дольше N дней. Полная ширина, здесь уместны таблицы и графики.

**Карманный вебапп / мастер:** мои сделки на сегодня, что ждёт моего шага, поиск клиента.

**Экран в рейле (без чата):** список и поиск — потому что `chat` и `client` в подпись рейла
не приходят, и карточка «текущего клиента» там будет пустой.

---

## Шаг 5. MCP-руки

Глаголами бизнеса, а не эндпойнтами:

| Инструмент | Что делает |
|---|---|
| `find_client` | найти клиента каскадом ключей по чату, телефону, avito_id |
| `get_client_card` | карточка: компания, контакты, активные сделки |
| `list_deals` | сделки по фильтру: воронка, стадия, ответственный, «висит дольше N дней» |
| `get_deal` | сделка целиком с полями среза и датами процесса |
| `move_deal_stage` | передвинуть по воронке |
| `set_deal_fields` | заполнить поля среза |
| `add_deal_comment` | комментарий в ленту сделки |
| `link_chat_to_client` | связать чат с клиентом и записать `crmClientId` в свойства чата |
| `funnel_snapshot` | срез воронки на дату — для артефакта и недельного отчёта |
| `request_feature` | клиент попросил то, чего чешуйка не умеет: сохранить тикет |

**Записывающие инструменты кладут в очередь, а не бьют в Б24 напрямую** — иначе при недоступности
портала агент получит ошибку и начнёт выдумывать.

### Логи и недельный срез

Своё хранилище с первого дня — лента MCP-активности ядра живёт 30 дней и это журнал вызовов,
а не бизнес-событий. В недельном срезе: чем пользовались, сколько правок ушло в Б24 и сколько
отбилось, максимальная длина очереди, время недоступности портала, заявки на доработку.

---

## Шаг 6. SSI — настройки установки

| Группа | Поля |
|---|---|
| Доступ | адрес портала, вебхук или OAuth, адрес прокси |
| Охват | какие воронки синхронизируем, какие только читаем, какие игнорируем |
| Сопоставление | таблица «поле Б24 → поле чешуйки»: код, имя, тип, показывать ли в списке |
| Ключи | порядок каскада поиска клиента, формат нормализации телефона |
| Направление | по каждой группе полей: только чтение или двусторонне |
| Расписание | частота доборки, время ночной сверки |
| Видимость | кто видит все сделки, кто только свои |

Без заполненного сопоставления чешуйка **не включается** и честно пишет, чего не хватает.

## Шаг 7. Модуль в Конструкторе

Агент ходит в Б24 **только через модуль**, а не напрямую. В каталоге Конструктора уже есть готовый
**«Bitrix24 API»** — начинать с него, а не писать свой. Правки API портала чинятся в модуле и
не ломают агентов; агентов будет несколько.

## Шаг 8. Свойства чата

Чешуйка объявляет и заполняет: `crmClientId`, `crmCardUrl`, `crmClientName`, `crmOrders`,
`crmDealStage`, `Телефон`. Через них связь чата с CRM переживает перезапуск и доступна агентам.

## Шаг 9. Права

- скоупы Кобры: `chats:read` (чтение чатов и своих полей), `chats:write` (заметки и поля),
  `folders:read` / `folders:write` — если артефакт хранится в папке. Больше не просить;
- **видимость сделок ядро не ограничивает** — «менеджер видит своих» реализует сервер чешуйки;
- вебхук Б24 даёт полный доступ к порталу: хранить как боевой секрет, в интерфейс не отдавать,
  все обращения — только с сервера.

---

## Чек-лист

- [ ] справочник полей выгружен через `.get` батчами, имена сохранены у себя
- [ ] сопоставление полей лежит в SSI, а не в коде
- [ ] решено, что делать с воронкой 25 `[old]`, у которой 68 сделок за 2026
- [ ] стадии читаются из `crm.status.list`, не захардкожены
- [ ] поиск клиента — каскад из пяти ключей, телефон нормализуется
- [ ] найденный `crmClientId` пишется в свойства чата
- [ ] первичная загрузка постранично **по ID**, не по `start`
- [ ] чтения идут через `batch`, лимит 2 запроса в секунду соблюдён
- [ ] прокси к порталу заложен в развёртывание
- [ ] портал выключили — интерфейс работает, правки копятся, после включения досылаются без дублей
- [ ] конфликт не теряется молча: оператор видит, что правка не применилась
- [ ] записывающие MCP-инструменты кладут в очередь
- [ ] экран в рейле работает без контекста чата
- [ ] вебхук Б24 не покидает сервер

## Где обычно ломается

1. **Поиск по одному ключу** — 7 попаданий из 17 вместо 17 из 17. Каскад обязателен.
2. **Телефон с ведущей восьмёркой** — `89966203893` не находит ничего, `+79966203893` находит.
3. **Синхронизация всех 187 полей** — 80 из них мертвы, у остальных имена приходится добывать
   поштучно. Болото, из которого не выбраться.
4. **Пометка `[old]` как признак мёртвой воронки** — 68 сделок 2026 года выпадут молча.
5. **Захардкоженные стадии** — продажи меняют воронку, чешуйка показывает вчерашний день.
6. **Постраничность по `start` на 9,6 тысячах сделок** — часть записей не доедет.
7. **Сквозные вызовы Б24 из интерфейса** — портал прилёг, и панель у оператора легла вместе с ним.
8. **Молчаливый проигрыш конфликта** — человек уверен, что изменил стадию, а её перезаписал Б24.

## Источники

- Разведка портала `bot-marketing.bitrix24.ru`, 28.08.2026: объёмы, воронки, стадии,
  заполняемость 187 пользовательских полей на 300 свежих сделках
- [Спецификация чешуйки](manifest-chesuyka.md) — мерка, поверхности, буфер, SSI, права
- B24 #87791 — каскад ключей и нормализация телефона, разбор реального сбоя у Motorland
- Каталог Конструктора — готовый модуль «Bitrix24 API»

---

_Источник: `cobra-components/cheshuyka-crm.md` в репозитории audio-talks. Эта копия обновляется скриптом `sync-components.mjs` — правки вносить в источник, не здесь._