REST: crm.status (справочники статусов)

crm.status — универсальный механизм справочников CRM Битрикс24. Через него читаются и редактируются стадии сделок и лидов, источники, типы контактов и десятки других списков. Разберём сущности справочников, поля элементов и семантику стадий.

Что такое справочники CRM

Почти все выпадающие списки в карточках CRM — это справочники. Каждый справочник определяется идентификатором сущности ENTITY_ID, а его элементы — это статусы со своим STATUS_ID, названием и сортировкой. Единый набор методов crm.status.* работает со всеми справочниками одинаково:

• crm.status.list — получить элементы (с фильтром по ENTITY_ID);
• crm.status.add — добавить элемент;
• crm.status.update — изменить;
• crm.status.delete — удалить;
• crm.status.get — получить один элемент по внутреннему ID;
• crm.status.fields — описание полей;
• crm.status.entity.types — список всех доступных справочников.

Начать знакомство с конкретным порталом стоит именно с crm.status.entity.types — он покажет, какие справочники существуют и какие из них можно редактировать.

Идентификаторы справочников

Каждый список имеет свой ENTITY_ID. Вот наиболее востребованные:

Чтение справочника

Получим стадии основной воронки сделок:

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

{
  "order":  { "SORT": "ASC" },
  "filter": { "ENTITY_ID": "DEAL_STAGE" },
  "select": [ "STATUS_ID", "NAME", "SORT", "SEMANTICS", "COLOR" ]
}

Ответ вернёт массив стадий. Поле STATUS_ID — это как раз то значение, которое подставляется в STAGE_ID сделки. Так интеграция узнаёт реальные коды стадий портала вместо того, чтобы «зашивать» их в код.

Поля элемента и семантика

Элемент справочника описывается компактным набором полей.

Поле SEMANTICS критично для стадий: именно оно, а не название, говорит системе, считать ли стадию выигрышной. При переносе сделки на стадию с семантикой P она автоматически помечается как успешно закрытая.

Добавление и изменение стадий

Добавим промежуточную стадию в основную воронку:

// crm.status.add
{
  "fields": {
    "ENTITY_ID": "DEAL_STAGE",
    "STATUS_ID": "APPROVAL",
    "NAME": "Согласование",
    "SORT": 45,
    "COLOR": "#47D1E2"
  }
}

Метод вернёт внутренний числовой ID элемента — его используют в crm.status.update и crm.status.delete. Обратите внимание: правится элемент по этому внутреннему ID, а не по STATUS_ID.

Практика: где это нужно

• Маппинг статусов. Перед синхронизацией сделок между Битрикс24 и внешней системой выгрузите справочники и постройте таблицу соответствия кодов.
• Динамика воронок. Если у клиента появляются новые направления, не хардкодьте стадии — читайте их через crm.status.list при каждом запуске обмена.
• Кэширование. Справочники меняются редко — кэшируйте их на стороне интеграции и обновляйте по расписанию, а не при каждом обращении.
• Проверка семантики. Для отчётов по конверсии ориентируйтесь на SEMANTICS, а не на названия, которые заказчик может переименовать.

Итог

Семейство crm.status.* — единый ключ ко всем справочникам CRM: стадиям, источникам, типам. Читайте их через crm.status.list по ENTITY_ID, различайте STATUS_ID и внутренний ID, уважайте SEMANTICS и не трогайте системные элементы.

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