REST: crm.category (воронки/направления)

Воронка (направление) в Битрикс24 — это набор стадий для конкретного типа продаж. Универсальное семейство crm.category.* управляет воронками сделок и смарт-процессов через единый интерфейс с параметром entityTypeId. Разберём методы, стадии и связь со старым crm.dealcategory.

Направления, воронки и entityTypeId

В интерфейсе это называется «направление», в API — «категория» (category). Каждое направление принадлежит типу сущности, который задаётся числовым entityTypeId: для сделок — 2, для лидов — 1, для смарт-процессов — их индивидуальные id от 128.

Универсальные методы работают одинаково для любого поддерживающего направления типа:

• crm.category.list — список направлений типа;
• crm.category.get — одно направление;
• crm.category.add — создать;
• crm.category.update — изменить;
• crm.category.delete — удалить;
• crm.category.fields — поля направления;
• crm.category.default.get / crm.category.default.set — направление по умолчанию.

Получение списка воронок

Каждый вызов требует entityTypeId — без него метод не знает, для какой сущности возвращать направления. Запросим воронки сделок:

POST /rest/1/xxxxxx/crm.category.list.json

{
  "entityTypeId": 2
}

В ответе — массив categories с полями id, name, sort, isDefault. Значение id — это тот самый CATEGORY_ID, который передаётся при создании сделки. Основная воронка сделок всегда имеет id = 0.

Создание направления

Создадим новое направление для сделок:

// crm.category.add
{
  "entityTypeId": 2,
  "fields": {
    "name": "Оптовые продажи",
    "sort": 200
  }
}

Метод вернёт объект category с присвоенным id. Сразу после создания у направления появляется базовый набор стадий — их можно донастроить. Изменение имени и сортировки выполняется через crm.category.update с указанием entityTypeId и id.

Стадии направления

Сами стадии внутри направления — это справочник статусов. Для новой модели их отдаёт метод crm.category.stages, которому передают id направления:

// crm.category.stages
{
  "id": 7
}

Под капотом стадии хранятся в справочнике вида DEAL_STAGE_<id> (для сделок) или DYNAMIC_<entityTypeId>_STAGE_<id> (для смарт-процессов). Поэтому добавлять и переименовывать стадии удобно через crm.status.add и crm.status.update.

Старый crm.dealcategory

До появления универсального crm.category воронками сделок управлял отдельный набор crm.dealcategory.*: crm.dealcategory.list, crm.dealcategory.add, crm.dealcategory.stage.list и другие. Он всё ещё работает, но применим только к сделкам.

• Для новых интеграций предпочтительнее crm.category — он единообразно покрывает сделки и смарт-процессы;
• crm.dealcategory.stage.list удобен, когда нужно быстро получить стадии одной воронки сделок без выяснения имени справочника;
• смешивать оба подхода в одном обмене не стоит — выберите один и придерживайтесь его.

Итог

Семейство crm.category.* — современный способ управлять воронками и направлениями: один интерфейс для сделок и смарт-процессов, обязательный entityTypeId, направление по умолчанию и стадии через связку с crm.status. Старый crm.dealcategory оставляйте для унаследованного кода.

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