CRM: обзор разделов и методов
Методы CRM управляют клиентской базой Битрикс24: лидами, сделками, контактами, компаниями, коммерческими предложениями, счетами и смарт-процессами. Они создают и обновляют элементы, ведут их по воронкам и стадиям, записывают историю работы в таймлайн, формируют документы и запускают автоматизацию.
Для новой разработки предназначены методы CRM в REST 3.0, они вызываются по адресу /rest/api/. Методы предыдущей версии API вызываются по адресу /rest/ и сохранены для поддержки существующих интеграций.
Выберите инструмент для разработки с AI-агентом:
- используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
- используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
Быстрый переход: все разделы и методы
Пользовательская документация: CRM в Битрикс24
Какую версию API выбрать
|
Если вам нужно |
Открывайте раздел |
|
Начать новую интеграцию: работать с элементами CRM и смарт-процессов, их полями, воронками и стадиями, товарами, реквизитами, адресами, делами и видами карточки |
|
|
Принимать заявки с сайта и создавать по ним объекты CRM |
|
|
Настроить типы смарт-процессов, работать с таймлайном, документами, автоматизацией и другими разделами, которых нет в REST 3.0 |
|
|
Поддерживать существующую интеграцию на методах по адресу |
|
|
Перенести интеграцию с методов предыдущей версии на REST 3.0 |
Тип объекта в имени метода
В REST 3.0 тип объекта входит в имя метода: crm.<тип>.<действие>. Например, crm.deal.add создает сделку, crm.smartprocess1038.add — элемент смарт-процесса с идентификатором типа 1038. Поэтому в документации одна страница на действие для всех типов, а в начале страницы — таблица с полным именем метода для каждого типа.
|
Тип объекта |
Сегмент в имени метода |
Пример |
|
Сделка |
|
|
|
Лид |
|
|
|
Контакт |
|
|
|
Компания |
|
|
|
Предложение |
|
|
|
Счет |
|
|
|
Моя компания |
|
|
|
Документ CRM |
|
|
|
Документ КЭДО |
|
|
|
Смарт-процесс |
|
|
Идентификатор типа смарт-процесса entityTypeId возвращает метод crm.type.list. В REST 3.0 аналога этого метода нет, вызывайте его по адресу предыдущей версии /rest/.
Имя метода пишется в нижнем регистре: crm.smartinvoice.add и crm.deal.productrow.list, а не crm.smartInvoice.add и crm.deal.productRow.list. Метод с другим регистром или с несуществующим типом, например crm.smartprocess99999.add, вернет ошибку BITRIX_REST_V3_EXCEPTION_METHODNOTFOUNDEXCEPTION со статусом 404.
Видимость системных полей
Настройка «Видимость полей» позволяет администратору ограничить круг пользователей, которым видно настраиваемое системное поле CRM. Для сделок и смарт-процессов ограничение можно задать в отдельной воронке или на уровне «Все воронки». У лидов и предложений без воронок используется общий уровень. У контактов и компаний уровня «Все воронки» нет: настройка действует только в выбранной категории, в том числе в категории обычных контактов или компаний.
Ограничения действуют, только если администратор настроил видимость поля. Без настроек видимости поля не скрываются. Ограничения не распространяются на администраторов портала и администраторов CRM. Право настраивать видимость само по себе не освобождает пользователя от ограничений.
Какие поля можно скрыть
Состав настраиваемых полей зависит от типа объекта. Например, у сделки можно скрыть тип TYPE_ID, вероятность PROBABILITY, комментарий COMMENTS, источник SOURCE_ID, описание источника SOURCE_DESCRIPTION, UTM-метки, привязки к клиенту и своей компании, даты начала и завершения.
Не каждое системное поле поддерживает эту настройку. Например, у сделки нельзя скрыть ID, TITLE, CATEGORY_ID, STAGE_ID, OPPORTUNITY, CURRENCY_ID и ответственного ASSIGNED_BY_ID. Поля, которые не входят в перечень настраиваемых для данного типа объекта, также не скрываются этой настройкой.
Методы предыдущей версии API
В методах crm.deal.*, crm.lead.*, crm.contact.*, crm.company.*, crm.quote.* и других прокси элементов CRM закрытое для пользователя поле при чтении обрабатывается как неизвестное:
*.fieldsне возвращает описание поля, если оно закрыто хотя бы в одной воронке или категории*.getи*.listне возвращают ключ и значение закрытого поля; применяется правило воронки или категории конкретного элемента- условие
filterи ключorderпо закрытому полю молча отбрасываются, ответ приходит без ошибки видимости поля. При определении закрытых полей для фильтрации и сортировки учитываются все воронки или категории типа объекта
Например, если SOURCE_ID закрыто для пользователя, фильтр по нему не сужает выборку: запрос выполняется как без этого условия. Явное указание поля в select не возвращает его значение.
Ограничение чтения в этих прокси не блокирует запись закрытого поля через методы добавления и изменения. Обычные проверки прав и значений полей сохраняются.
Универсальные методы crm.item.* учитывают видимость следующим образом:
crm.item.fieldsисключает описание поля, закрытого хотя бы в одной воронке или категории типа объектаcrm.item.getиcrm.item.listисключают закрытые ключи и значения с учетом воронки или категории каждого элемента, в том числе при явном выборе поляcrm.item.listмолча отбрасывает условияfilterи ключиorderпо закрытым полям, учитывая ограничения во всех воронках или категориях типа объекта
Отдельные методы учитывают ограничения при изменении дел и поиске дубликатов:
crm.activity.updateисключает из входных данных поля, закрытые для пользователя в контексте дела. Если после этого из непустого набора полей ничего не осталось, метод возвращаетtrueбез измененийcrm.duplicate.findbycommищет совпадения только в тех типах объектов и категориях, где запрошенный тип коммуникации открыт пользователю. Совпадения по скрытому телефону или e-mail не возвращаются и не занимают места в лимите поиска; если искать негде, результат пустой
REST 3.0
В REST 3.0 условие фильтра по закрытому системному полю приводит к ошибке BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION со статусом HTTP 400. Это относится и к закрытым типам множественных полей, например телефону или e-mail, и к вложенным условиям по закрытому полю.
Явный выбор закрытого системного поля в select методов получения и списка элементов также приводит к этой ошибке.
Какие методы есть у типа объекта
Не все группы методов REST 3.0 доступны для каждого типа. Например, стадии есть только у сделок и смарт-процессов, а реквизиты — у контактов и компаний.
|
Группа методов |
deal |
lead |
contact |
company |
quote |
smartinvoice |
mycompany |
smartdocument |
smartb2edocument |
smartprocess |
|
+ |
+ |
+ |
+ |
+ |
+ |
+ |
— |
— |
+ |
|
|
Основной контакт |
+ |
+ |
— |
— |
+ |
+ |
— |
+ |
+ |
+ |
|
Описание полей |
+ |
+ |
+ |
+ |
+ |
+ |
+ |
— |
— |
+ |
|
+ |
+ |
+ |
+ |
+ |
+ |
— |
— |
— |
+ |
|
|
+ |
— |
+ |
+ |
— |
— |
— |
— |
— |
+ |
|
|
+ |
— |
— |
— |
— |
— |
— |
— |
— |
+ |
|
|
+ |
+ |
— |
— |
+ |
+ |
— |
+ |
— |
+ |
|
|
— |
— |
+ |
+ |
— |
— |
— |
— |
— |
— |
|
|
+ |
— |
— |
— |
+ |
+ |
— |
+ |
— |
+ |
|
|
+ |
— |
— |
— |
— |
+ |
— |
— |
— |
— |
|
|
— |
+ |
+ |
+ |
— |
— |
— |
— |
— |
— |
|
|
+ |
+ |
+ |
+ |
+ |
+ |
— |
+ |
+ |
+ |
|
|
+ |
+ |
+ |
+ |
+ |
+ |
— |
+ |
— |
+ |
Справочники и режим лидов не привязаны к типу объекта: crm.dictionary.<справочник>.*, crm.lead.isenabled, crm.lead.enable, crm.lead.disable.
Точный перечень методов вашего Битрикс24 возвращает OpenAPI-документация.
Методы смарт-процесса зависят от настроек типа
У смарт-процесса «+» в таблице означает, что группа есть при включенной настройке типа:
- без воронок
isCategoriesEnabledнет методов воронок и стадий - без стадий
isStagesEnabledнет методов стадий - без товаров
isLinkWithProductsEnabledнет методов товарных позиций - без привязки клиента
isClientEnabledнет методаsetprimarycontact
От настроек зависит и состав полей. Какие поля пропадают без каждой настройки, описано на странице полей смарт-процесса.
Как начать работу
- Определите тип объекта и имя метода по таблице Тип объекта в имени метода. Для смарт-процесса получите
entityTypeIdметодом crm.type.list - Узнайте поля типа на его странице полей, например Поля сделки, или методом crm.<тип>.field.list
- Создайте элемент методом crm.<тип>.add
- Получите элементы методом crm.<тип>.list. Без параметра
selectметодыgetиlistвозвращают толькоid: перечислите нужные поля вselect - Добавьте к элементу товары, реквизиты или адреса методами соответствующей группы из обзора методов
Чем REST 3.0 отличается от предыдущей версии и как перенести на него существующую интеграцию, описано на странице Переход на новые методы CRM.
Частые кейсы и сценарии
Виджеты
Приложение можно встроить в карточку или список объектов CRM — своей вкладкой, пунктом меню карточки, списка или аналитики, кнопкой над таймлайном или в воронках продаж. Все точки и параметры, которые приходят обработчику, собраны в разделе Места встраивания CRM.
Связь с другими объектами
Объекты CRM связаны с пользователями Битрикс24, задачами, торговым каталогом, телефонией и CRM-формами.
Пользователи. Ответственный за объект CRM хранится в поле assignedById в REST 3.0 и универсальных методах и в поле 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.
CRM-формы. Заполнение CRM-формы создает лид, сделку, предложение или элемент смарт-процесса. Формы создают и настраивают методы REST 3.0 crm.form.*.
Обзор разделов и методов
Scope:
crmКто может выполнять метод: в зависимости от метода
Методы REST 3.0
|
Раздел |
Что делают методы |
|
Создают, изменяют, получают, считают и удаляют элементы CRM, работают с множественными полями и основным контактом. Здесь же страницы полей каждого типа объекта |
|
|
Возвращают описание полей, создают пользовательские поля и значения списков, задают обязательность полей |
|
|
Создают и настраивают воронки и стадии сделок и смарт-процессов, воронки контактов и компаний |
|
|
Добавляют, изменяют и заменяют товары в сделках, лидах, предложениях, счетах, документах и смарт-процессах |
|
|
Работают с реквизитами, банковскими реквизитами и адресами реквизитов контактов и компаний, привязывают реквизиты клиента и моей компании к элементам |
|
|
Работают с адресами контактов, компаний и лидов |
|
|
Настраивают разделы и поля карточки элемента, выбирают вид для пользователя и общий вид |
|
|
Получают, завершают и удаляют дела, управляют привязками дел к элементам, работают с письмами. Создают дела и комментарии методы таймлайна предыдущей версии |
|
|
Возвращают и изменяют справочники CRM: типы сделок и контактов, источники, обращения, сферы деятельности и другие |
|
|
Проверяют, включают и выключают лиды в CRM |
|
|
Создают, настраивают, включают и удаляют CRM-формы, получают код для размещения на сайте |
Разделы, которых нет в REST 3.0
Эти методы вызываются по адресу предыдущей версии /rest/.
|
Раздел |
Что делают методы |
|
Создают и настраивают типы смарт-процессов. Идентификатор типа |
|
|
Создают дела, комментарии, записи и другие элементы таймлайна |
|
|
Формируют документы по шаблонам, управляют шаблонами и нумераторами |
|
|
Запускают webhook-триггеры и регистрируют триггеры приложения |
|
|
Создают и настраивают цифровые рабочие места смарт-процессов |
|
|
Управляют валютами CRM, базовой валютой и локализацией |
|
|
Создают списки обзвона и управляют их статусами |
|
|
Ищут и объединяют дублирующиеся записи CRM |
|
|
Создают трейсы и привязывают объекты CRM к источникам обращения |
|
|
Возвращает историю перемещения элементов по стадиям |
Предыдущая версия API
Для поддержки существующих интеграций сохранены универсальные методы crm.item.*, методы сделок, лидов, контактов, компаний и предложений, реквизиты, справочники crm.status.* и вспомогательные объекты. Они собраны в разделе Предыдущая версия API.