CRM: обзор разделов и методов

Методы CRM управляют клиентской базой Битрикс24: лидами, сделками, контактами, компаниями, коммерческими предложениями, счетами и смарт-процессами. Они создают и обновляют элементы, ведут их по воронкам и стадиям, записывают историю работы в таймлайн, формируют документы и запускают автоматизацию.

Например, можно создать смарт-процесс, настроить его структуру и затем работать с его элементами через универсальные методы CRM.

Быстрый переход: все разделы и методы

Пользовательская документация: CRM в Битрикс24

Как начать работуКак начать работу

1. Определите тип объекта. Числовые идентификаторы entityTypeId всех типов, включая смарт-процессы, возвращает crm.enum.ownertype. Настройки самих смарт-процессов — включены ли воронки, стадии, автоматизация и другие возможности типа — возвращает crm.type.list
2. Получите состав полей объекта методом crm.item.fields. Для сделок и смарт-процессов заранее подберите воронку categoryId — crm.category.list — и стадию stageId — crm.status.list
3. Создайте элемент методом crm.item.add и обновляйте его методом crm.item.update
4. Читайте данные: один элемент по идентификатору возвращает crm.item.get, выборку — crm.item.list. Списочные методы CRM отдают до 50 элементов за запрос, следующую страницу выбирают параметром start — подробности в статье Особенности работы списочных методов

На изменения объектов можно подписаться событиями: они описаны в разделах самих объектов, например события сделок и события элементов смарт-процессов.

CRM работает в классическом режиме с лидами или в простом режиме без лидов. Текущий режим возвращает crm.settings.mode.get. В простом режиме сделку создают сразу, без предварительного лида.

Универсальные методы или методы объектаУниверсальные методы или методы объекта

Универсальные методы crm.item.* работают через entityTypeId и покрывают основные операции: создание, чтение, обновление и фильтрацию. Они подходят для лидов, сделок, контактов, компаний, предложений и счетов, а для смарт-процессов это единственный способ работать с элементами. Актуальный тип счета — SMART_INVOICE с entityTypeId = 31.

Если операция касается только одного типа объекта — например, связей сделок с контактами — используйте методы нужного раздела: crm.deal.*, crm.lead.*, crm.contact.*, crm.company.*, crm.quote.*.

Внутри раздела универсальных методов есть подтемы: воронки, разделы детальной карточки, товарные позиции, счета, оплаты и доставки, привязка заказов, пользовательские поля и их настройки, типы смарт-процессов, импорт данных и события.

Старые ветки методов CRM не развиваются. Счета заменяют универсальные методы для счетов, а их стадиями управляет справочник SMART_INVOICE_STAGE_xx в методах crm.status.*. Товарные позиции заменяют crm.item.productrow.*, направления сделок — crm.category.*, а товары, каталоги, разделы каталога и единицы измерения — методы торгового каталога.

Имена полей в двух ветках методов различаются: универсальные методы используют camelCase, методы объекта — UPPER_CASE. Стадия сделки приходит в поле stageId в crm.item.get и в поле STAGE_ID в crm.deal.get. Правила преобразования имен описаны в разделе Универсальные методы CRM.

Что входит в карточку CRMЧто входит в карточку CRM

Карточка CRM объединяет данные объекта, этап работы с ним и историю взаимодействий.

Поля. В карточке хранятся данные объекта, состав которых зависит от его типа. Список доступных полей можно получить методом crm.item.fields. Общие поля описаны в статье Поля основных объектов CRM. Пользовательские поля настраивают методами userfieldconfig.add или userfieldconfig.update — им нужны scope userfieldconfig и scope модуля из moduleId, для CRM это crm, а также право «Разрешить изменять настройки».

Воронка и стадия. Для сделок и смарт-процессов карточка показывает, в какой воронке находится объект и на каком этапе. Для работы с воронками нужен categoryId — его возвращает crm.category.list. Стадии возвращает crm.status.list с фильтром по справочнику ENTITY_ID: DEAL_STAGE — стадии основной воронки сделок, DEAL_STAGE_1 — стадии воронки с categoryId = 1. Код стадии приходит в поле STATUS_ID: у основной воронки это NEW или PREPARATION, у дополнительной — с префиксом воронки, например C1:NEW. Этот код передают в поле stageId универсальных методов или STAGE_ID методов объекта.

Таймлайн. В таймлайне хранится история работы с объектом CRM: дела и комментарии. Чтобы добавить запись в карточку объекта, обычно создают универсальное дело методом crm.activity.todo.add или комментарий методом crm.timeline.comment.add.

Документы. Документы формируют по шаблонам генератора документов: шаблон добавляют методом crm.documentgenerator.template.add, а сам документ создают и привязывают к объекту CRM методом crm.documentgenerator.document.add.

Автоматизация. Карточка участвует в сценариях автоматизации, которые зависят от состояния объекта. Собственный триггер приложение регистрирует методом crm.automation.trigger.add и запускает методом crm.automation.trigger.execute — оба метода работают только в контексте приложения.

Смарт-процессыСмарт-процессы

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

Для смарт-процесса, в отличие от стандартных объектов, сначала настраивают структуру. Тип создают методом crm.type.add — в ответе возвращается entityTypeId нового смарт-процесса. Список существующих типов и их entityTypeId возвращает crm.type.list.

Пользовательские поля добавляют методом userfieldconfig.add. При необходимости отдельно настраивают воронки методом crm.category.add и стадии — crm.status.add.

После настройки структуры работают с элементами через методы crm.item.* — так же, как и со стандартными объектами CRM.

ВиджетыВиджеты

Приложение можно встроить в карточку или список объектов CRM — своей вкладкой, пунктом меню карточки, списка или аналитики, кнопкой над таймлайном или в воронках продаж. Все точки, поддержанные типы объектов и параметры, которые приходят обработчику, собраны в разделе Места встраивания CRM, общий механизм — в статье Механизм встраивания виджетов.

Код точки собирают по шаблону вида CRM_XXX_DETAIL_TAB: вместо XXX подставьте LEAD, DEAL, CONTACT, COMPANY, QUOTE, SMART_INVOICE, ORDER или ACTIVITY, а для смарт-процессов — DYNAMIC_ и числовой идентификатор типа, например CRM_DYNAMIC_183_DETAIL_TAB.

Второй способ встройки — пользовательское поле, в котором загружается интерфейс приложения. Готовый пример разобран в туториале Встроить виджет в карточку CRM.

Ключевые идентификаторыКлючевые идентификаторы

Идентификатор	Что означает	Где используется	Каким методом получить
entityTypeId	Тип объекта CRM	Универсальные методы, воронки, пользовательские поля	Все типы, включая смарт-процессы, — crm.enum.ownertype; настройки смарт-процесса — crm.type.list
id	Идентификатор элемента CRM	Чтение, обновление, связи между объектами	Из списка элементов crm.item.list или после создания элемента crm.item.add
categoryId	Идентификатор воронки	Сделки и смарт-процессы — нужен при создании и фильтрации элементов	Из списка воронок crm.category.list
stageId	Идентификатор стадии	Создание и фильтрация элементов сделок и смарт-процессов	Из списка стадий crm.status.list с фильтром по ENTITY_ID

Связь с другими объектамиСвязь с другими объектами

Объекты CRM связаны с пользователями Битрикс24, задачами, торговым каталогом и телефонией.

Пользователи. Ответственный за объект CRM хранится в поле assignedById в универсальных методах и ASSIGNED_BY_ID в методах объекта. Данные пользователя можно получить методами user.get или user.search.

Задачи. Задачи связывают с объектами CRM через множественное поле UF_CRM_TASK. В нем передают массив идентификаторов с префиксом типа объекта, например ["D_10", "C_7"]. Префиксы перечислены в статье Типы данных и структура объектов. Связь записывают при создании задачи методом tasks.task.add, а читают — методом tasks.task.get. Чтобы поле принимало элементы смарт-процесса, у типа объекта включают привязку к задачам параметром linkedUserFields в методе crm.type.update.

Каталог. Товарные позиции в сделках и коммерческих предложениях берутся из торгового каталога. Управлять товарами можно методами catalog.product.*.

Телефония. Звонки создают дела в таймлайне CRM. Метод telephony.externalcall.finish завершает звонок и возвращает идентификатор созданного дела в параметре CRM_ACTIVITY_ID.

Обзор разделов и методовОбзор разделов и методов

Scope: crm

Кто может выполнять метод: в зависимости от метода

Справочные материалыСправочные материалы

Статья	Описание
Типы данных и структура объектов в REST API CRM	Что такое entityTypeId, какие бывают идентификаторы и как устроены объекты CRM
Поля основных объектов CRM	Поля ключевых объектов CRM в одном месте
Частые кейсы и туториалы	Прикладные сценарии и примеры использования CRM

Объекты CRMОбъекты CRM

Раздел	Когда использовать	Ключевые методы
Универсальные методы CRM	Для работы с объектами CRM и смарт-процессами через entityTypeId	crm.item.add, crm.item.update, crm.item.list Все методы раздела
Сделки	Для работы со сделками, их карточками и связями с контактами	crm.deal.add, crm.deal.update, crm.deal.list Все методы раздела
Лиды	Для работы с лидами, их карточками и связями с контактами	crm.lead.add, crm.lead.update, crm.lead.list Все методы раздела
Контакты	Для работы с контактами, их карточками и связями с компаниями	crm.contact.add, crm.contact.update, crm.contact.list Все методы раздела
Компании	Для работы с компаниями, их карточками и связями с контактами	crm.company.add, crm.company.update, crm.company.list Все методы раздела
Коммерческие предложения	Для работы с коммерческими предложениями и товарными позициями	crm.quote.add, crm.quote.update, crm.quote.list Все методы раздела

Настройки и справочникиНастройки и справочники

Раздел	Когда использовать	Ключевые методы
Справочники	Для управления системными списками CRM: стадиями, источниками, типами	crm.status.add, crm.status.update, crm.status.list Все методы раздела
Валюты	Для управления валютами CRM, базовой валютой и локализацией	crm.currency.add, crm.currency.update, crm.currency.list Все методы раздела
Реквизиты	Для работы с реквизитами, адресами и банковскими данными CRM	crm.requisite.add, crm.requisite.update, crm.requisite.list Все методы раздела

Дела и документыДела и документы

Раздел	Когда использовать	Ключевые методы
Таймлайн и дела	Для работы с делами, комментариями, звонками и другими записями таймлайна	crm.activity.todo.add, crm.timeline.comment.add Все методы раздела
Список обзвона	Для создания списков обзвона и управления их статусами	crm.calllist.add, crm.calllist.list Все методы раздела
Генератор документов	Для формирования документов по шаблонам и управления шаблонами и нумераторами	crm.documentgenerator.document.add, crm.documentgenerator.template.list Все методы раздела

Автоматизация и аналитикаАвтоматизация и аналитика

Раздел	Когда использовать	Ключевые методы
Автоматизация CRM	Для запуска настроенных webhook-триггеров и регистрации триггеров приложения	crm.automation.trigger, crm.automation.trigger.add, crm.automation.trigger.execute Все методы раздела
Сквозная аналитика	Для создания трейсов и привязки объектов CRM к источникам обращения	crm.tracking.trace.add, crm.tracking.trace.delete Все методы раздела

Дополнительные инструментыДополнительные инструменты

Раздел	Когда использовать	Ключевые методы
Поиск и обработка дубликатов	Для поиска и объединения дублирующихся записей CRM	crm.duplicate.findbycomm, crm.entity.mergeBatch Все методы раздела
Цифровые рабочие места	Для создания и настройки цифровых рабочих мест смарт-процессов	crm.automatedsolution.add, crm.automatedsolution.list Все методы раздела
Вспомогательные объекты	Для работы с перечислениями, множественными полями и другими служебными объектами CRM	crm.enum.ownertype Все методы раздела

Отдельные методыОтдельные методы

Метод	Описание
crm.settings.mode.get	Возвращает текущий режим работы CRM
crm.stagehistory.list	Возвращает историю движения объекта по стадиям