#CRM: режимы работы

Статус: Планируется. Режим CRM (internal / external / both) и публичный API лидов пока не реализованы: сегодня платформа работает только как «наша CRM» (режим internal, без выбора). Страница фиксирует замысел из проекта публичного API. Все названия полей, путей и событий могут измениться до выхода. Сроки не обещаются.

Платформа Формула ИИ ведёт лиды сама: лид создаётся из диалога с ИИ-продажником, с формы, из предзаписи и других источников, получает оценку, статус и ответственного. Если у вашей организации уже есть своя CRM (amoCRM, Bitrix24, HubSpot или собственная система), возникает вопрос: кто именно главный в каждый момент жизни лида. Режим CRM отвечает на него.

Доступ: области leads:read, leads:write, leads:score (подробно — API лидов); режим меняется только в кабинете. Платно: только оценка (leads:score). ПДн: да, контакт лида содержит имя, почту и телефон — см. Передача ПДн.

#Главное правило: лид всегда у нас

Какой бы режим вы ни выбрали, лид всегда существует на платформе Формула ИИ. Он связан с диалогом, атрибуцией (откуда пришёл человек), оценкой и памятью ИИ-продажника — без этого агент не может продолжать разговор. Режим меняет не наличие лида у нас, а то, кто владеет его полями: статусом, ответственным, исходом.

Внешняя CRM не «забирает» лид: она получает его копию и ведёт свой процесс, а мы остаёмся источником диалога, атрибуции и оценки.

#Три режима

Режим хранится в настройках арендатора (settings.crm.mode) и действует на весь арендатор. Текущий режим интеграция видит в GET /me (crm_mode).

Режим	Кто источник истины по статусу, ответственному, исходу	Что делают наши агенты	Наш экран CRM
`internal` (по умолчанию)	Наша CRM	Пишут в нашу CRM. События уходят подписчикам вебхуков, если они есть	Рабочий инструмент
`external`	До принятия лида — мы. После принятия — внешняя CRM	Не меняют статус сами: шлют внешней CRM «запрос действия» (`lead.action_requested`) и ждут подтверждения или отказа	Проекция только для чтения
`both`	Поле за полем по таблице владения (ниже)	Пишут в нашу CRM и шлют события; изменения внешней CRM принимаются по API с проверкой версии	Рабочий инструмент

Режим по умолчанию — internal: так платформа ведёт себя сегодня. Подключение API лидов его не меняет.

#Принятие лида (режим `external`)

Лид проходит две фазы.

До принятия. Лид наш: мы создаём его, оцениваем, ведём диалог. Внешняя CRM получает событие lead.created и решает, нужен ли ей этот лид.
После принятия. Внешняя CRM вызывает POST /leads/{id}/accept. С этого момента:
- статус, ответственный, исход и причина потери принадлежат внешней CRM;
- наши агенты прекращают собственные касания лида: больше не меняют статус, не ставят задач, не отправляют дожим по своему решению;
- вместо действия агент создаёт запрос lead.action_requested (см. Действия агентов), который внешняя CRM подтверждает или отклоняет;
- наш экран показывает лид как проекцию только для чтения.

Если арендатор переключит режим обратно на internal, принятые лиды снова становятся нашими — см. Переключение режима.

#Владение полями в режиме `both`

В режиме both обе системы могут менять лид, поэтому для каждого поля задан владелец.

Поле	Владелец	Правило
Статус, ответственный, исход, причина потери	Последняя запись с большей версией	При конфликте побеждает внешняя CRM
Оценка, флаги, intent, сводка ИИ	Мы	Внешняя CRM может добавить свою оценку (`external_score`), не заменяя нашу
Контакт (ФИО, почта, телефон)	Тот, кто изменил последним, с версией	Слияние контактов приходит событием
Атрибуция, источник	Мы	Записывается один раз, правке не подлежит

Версия — поле version лида: каждое изменение увеличивает её, а запись извне должна передать ожидаемую версию в If-Match (иначе 428 precondition_required; при расхождении 412 precondition_failed). Запись в поле, которым владеет другая сторона, отклоняется ответом 409 invalid_state. Подробности — в API лидов.

#Как выбрать режим

Ситуация	Режим
Вы работаете с лидами в нашем кабинете, внешней CRM нет	`internal`
Менеджеры работают только во внешней CRM; нам нужен диалог и оценка	`external`
Часть процесса (например, первичная квалификация) идёт у нас, дальнейшее — у вас; нужны обе стороны	`both`
Вы только хотите получать копии новых лидов в свою систему, а работать у нас	`internal` + подписка на `lead.created`

internal — режим по умолчанию; подписка на события не требует смены режима.

#Что видит внешняя CRM

События вебхуков v2. Нагрузка «тонкая» по умолчанию: идентификаторы, версия, тип; содержимое запрашивается по API. Подписка с флагом include_pii: true получает содержимое прямо в событиях lead.*, contact.*, conversation.* (Передача ПДн).

Событие	Когда
`lead.created`	Создан лид
`lead.updated`	Изменились поля (в нагрузке — версия)
`lead.scored`	Лид оценён
`lead.status_changed`	Изменился статус
`lead.action_requested`	Агент просит действие (режим `external`)
`conversation.handoff_requested`	ИИ-продажник просит передать диалог человеку; в `data` есть `lead_id`, если у диалога есть лид
`task.created`, `task.completed`	Создана и закрыта задача
`contact.merged`	Контакты объединены
`conversation.summary_ready`	Готова сводка диалога
`crm.mode_changed`	Арендатор переключил режим CRM

Отдельного события lead.handoff_requested нет: передача оператору приходит одним событием conversation.handoff_requested.

Конверт события, подпись и повторы доставки — в разделе о вебхуках.

#Переключение режима

Режим переключается только в кабинете, по праву владельца арендатора (integrations.manage и crm.settings). Через API режим не меняется. О каждом переключении подписчики получают событие crm.mode_changed.

Переход	Что происходит
`internal` → `external`	Открытые лиды остаются нашими, пока внешняя CRM не вызовет `POST /leads/{id}/accept`; принятые лиды переходят к внешней CRM
`external` → `internal`	Принятые лиды становятся нашими с последним известным состоянием. Открытые запросы действий (`requested`) истекают (`expired`)

Переходы с участием both в проекте не описаны — см. «Открытые вопросы».

#Открытые вопросы

Переходы между both и остальными режимами: судьба открытых запросов действий и порядок владения полями в момент переключения (техническое).
Состав data события crm.mode_changed (техническое; уточнится в OpenAPI).
Доступны ли режимы external и both на всех трёх ячейках одновременно (к владельцу).

См. также: ошибки, пагинация, идемпотентность, ячейки и данные.