REST: стадии и воронки

Стадии и воронки задают маршрут движения сделки от заявки до оплаты. В REST Битрикс24 стадии хранятся как справочники статусов (crm.status.*), а воронки-направления описываются методами crm.category.*.

Стадии, статусы и направления

Важно различать три понятия, которые в интерфейсе выглядят похоже:

• Статус лида — стадии обработки лида (справочник STATUS);
• Стадия сделки — этап продажи внутри воронки (справочник DEAL_STAGE);
• Направление (воронка) — набор стадий сделок; в API это «категория» (crm.category).

Такое разделение объясняет, почему в API за стадии и за воронки отвечают разные семейства методов. Стадии — это плоские справочники значений, привязанные к сущности и направлению. Воронки — это контейнеры стадий с собственными правами и настройками. При проектировании интеграции всегда начинайте с получения актуальных списков и не хардкодьте коды стадий: на разных порталах они отличаются.

Справочники статусов: crm.status.list

Все стадии и справочники CRM читаются одним методом crm.status.list с фильтром по ENTITY_ID:

Пример: crm.status.list с телом { "filter": { "ENTITY_ID": "DEAL_STAGE" }, "order": { "SORT": "ASC" } }.

Каждый элемент справочника содержит STATUS_ID (код), NAME (название), SORT (порядок) и служебные признаки. Полный перечень доступных справочников портала отдаёт метод crm.status.entity.types — с него удобно начинать, чтобы узнать точные ENTITY_ID под конкретную конфигурацию CRM.

Стадии сделок и формат STAGE_ID

Каждая стадия имеет код STATUS_ID внутри справочника. Для основной воронки код короткий: NEW, PREPARATION, WON, LOSE.

Для дополнительных воронок код получает префикс категории:

C7:NEW — стадия «новая» воронки с CATEGORY_ID = 7.

Воронки: crm.category и dealcategory

Современный универсальный способ управлять воронками — семейство crm.category.* с указанием типа сущности:

• crm.category.list с entityTypeId: 2 — воронки сделок;
• crm.category.get / add / update / delete — управление;
• crm.category.fields — состав полей категории.

Исторически для сделок существует и специализированное семейство crm.dealcategory.*: crm.dealcategory.list, crm.dealcategory.stage.list (стадии конкретной воронки), crm.dealcategory.default.get. Для новых интеграций предпочтителен crm.category.

Метод crm.dealcategory.stage.list удобен тем, что сразу возвращает стадии нужной воронки по её ID, без ручного составления ENTITY_ID. Если вы поддерживаете старую интеграцию, эти методы продолжают работать; переписывать их на crm.category имеет смысл при добавлении смарт-процессов, где старое семейство неприменимо.

Смена стадии и семантика

Перевод сделки на стадию — это обычный crm.deal.update с новым STAGE_ID. У каждой стадии есть машинная семантика SEMANTICS, определяющая её смысл независимо от названия:

Именно поэтому во внешней интеграции стоит хранить сопоставление своих статусов не с названиями стадий, а с их кодами и семантикой. Когда сайт или 1С сообщают «заказ оплачен», интеграция ищет стадию нужной воронки с семантикой успеха и переводит сделку на неё. Такой подход переживает переименования стадий менеджерами и не ломается при добавлении промежуточных этапов.

Перевод стадии — это полноценное событие CRM: срабатывают роботы, триггеры и бизнес-процессы, привязанные к этапу. Если интеграция массово двигает сделки, учитывайте нагрузку от автоматизации и, при необходимости, отключайте лишние уведомления через параметры метода.

Создание своих статусов

Добавить новую стадию или элемент справочника можно методом crm.status.add:

{ "fields": { "ENTITY_ID": "DEAL_STAGE_7", "STATUS_ID": "C7:APPROVAL", "NAME": "Согласование", "SORT": 40 } }

• crm.status.update — переименовать или пересортировать;
• crm.status.delete — удалить пользовательский элемент;
• crm.status.entity.types — список доступных справочников.

При создании стадии для дополнительной воронки её STATUS_ID обязан начинаться с префикса C{ID}:, а сортировка SORT определяет положение на канбане. Семантику новой стадии система вычисляет по её положению: крайняя правая «успешная» и «провальная» зоны формируются автоматически, поэтому после массового создания стадий стоит проверить итоговую семантику через crm.status.list.

Итог

Стадии и воронки в REST Битрикс24 — это связка справочников статусов и категорий. Понимание формата C{ID}:CODE, машинной семантики P/S/F и разницы между crm.category и crm.dealcategory избавляет от большинства ошибок при автоматическом движении сделок.

Мы в B2Bsite настраиваем воронки и автоматику перехода стадий под реальные процессы продаж, связывая их с событиями сайта и 1С. Если движение сделок должно быть управляемым и предсказуемым — поможем спроектировать логику стадий.