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

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

Для новой разработки предназначены методы CRM в REST 3.0, они вызываются по адресу /rest/api/. Методы предыдущей версии API вызываются по адресу /rest/ и сохранены для поддержки существующих интеграций.

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

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

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

Какую версию API выбрать

Если вам нужно

Открывайте раздел

Начать новую интеграцию: работать с элементами CRM и смарт-процессов, их полями, воронками и стадиями, товарами, реквизитами, адресами, делами и видами карточки

Методы REST 3.0

Принимать заявки с сайта и создавать по ним объекты CRM

CRM-формы

Настроить типы смарт-процессов, работать с таймлайном, документами, автоматизацией и другими разделами, которых нет в REST 3.0

Разделы только в предыдущей версии

Поддерживать существующую интеграцию на методах по адресу /rest/

Предыдущая версия API

Перенести интеграцию с методов предыдущей версии на REST 3.0

Переход на новые методы CRM

Тип объекта в имени метода

В REST 3.0 тип объекта входит в имя метода: crm.<тип>.<действие>. Например, crm.deal.add создает сделку, crm.smartprocess1038.add — элемент смарт-процесса с идентификатором типа 1038. Поэтому в документации одна страница на действие для всех типов, а в начале страницы — таблица с полным именем метода для каждого типа.

Тип объекта

Сегмент в имени метода

Пример

Сделка

deal

crm.deal.list

Лид

lead

crm.lead.list

Контакт

contact

crm.contact.list

Компания

company

crm.company.list

Предложение

quote

crm.quote.list

Счет

smartinvoice

crm.smartinvoice.list

Моя компания

mycompany

crm.mycompany.list

Документ CRM

smartdocument

crm.smartdocument.productrow.list

Документ КЭДО

smartb2edocument

crm.smartb2edocument.detailpagelayout.list

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

smartprocess<entityTypeId>

crm.smartprocess1038.list

Идентификатор типа смарт-процесса 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

Элементы

+

+

+

+

+

+

+

—

—

+

Основной контакт setprimarycontact

+

+

—

—

+

+

—

+

+

+

Описание полей field.get, field.list

+

+

+

+

+

+

+

—

—

+

Пользовательские поля и обязательность

+

+

+

+

+

+

—

—

—

+

Воронки

+

—

+

+

—

—

—

—

—

+

Стадии

+

—

—

—

—

—

—

—

—

+

Товарные позиции

+

+

—

—

+

+

—

+

—

+

Реквизиты и банковские реквизиты

—

—

+

+

—

—

—

—

—

—

Реквизиты клиента

+

—

—

—

+

+

—

+

—

+

Реквизиты моей компании

+

—

—

—

—

+

—

—

—

—

Адреса

—

+

+

+

—

—

—

—

—

—

Виды карточки

+

+

+

+

+

+

—

+

+

+

Дела

+

+

+

+

+

+

—

+

—

+

Справочники и режим лидов не привязаны к типу объекта: crm.dictionary.<справочник>.*, crm.lead.isenabled, crm.lead.enable, crm.lead.disable.

Точный перечень методов вашего Битрикс24 возвращает OpenAPI-документация.

Методы смарт-процесса зависят от настроек типа

У смарт-процесса «+» в таблице означает, что группа есть при включенной настройке типа:

  • без воронок isCategoriesEnabled нет методов воронок и стадий
  • без стадий isStagesEnabled нет методов стадий
  • без товаров isLinkWithProductsEnabled нет методов товарных позиций
  • без привязки клиента isClientEnabled нет метода setprimarycontact

От настроек зависит и состав полей. Какие поля пропадают без каждой настройки, описано на странице полей смарт-процесса.

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

  1. Определите тип объекта и имя метода по таблице Тип объекта в имени метода. Для смарт-процесса получите entityTypeId методом crm.type.list
  2. Узнайте поля типа на его странице полей, например Поля сделки, или методом crm.<тип>.field.list
  3. Создайте элемент методом crm.<тип>.add
  4. Получите элементы методом crm.<тип>.list. Без параметра select методы get и list возвращают только id: перечислите нужные поля в select
  5. Добавьте к элементу товары, реквизиты или адреса методами соответствующей группы из обзора методов

Чем 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-формы

Создают, настраивают, включают и удаляют CRM-формы, получают код для размещения на сайте

Разделы, которых нет в REST 3.0

Эти методы вызываются по адресу предыдущей версии /rest/.

Раздел

Что делают методы

Типы смарт-процессов

Создают и настраивают типы смарт-процессов. Идентификатор типа entityTypeId нужен для имени метода REST 3.0, например crm.smartprocess1038.add

Таймлайн и дела

Создают дела, комментарии, записи и другие элементы таймлайна

Генератор документов

Формируют документы по шаблонам, управляют шаблонами и нумераторами

Автоматизация CRM

Запускают webhook-триггеры и регистрируют триггеры приложения

Цифровые рабочие места

Создают и настраивают цифровые рабочие места смарт-процессов

Валюты

Управляют валютами CRM, базовой валютой и локализацией

Список обзвона

Создают списки обзвона и управляют их статусами

Поиск и обработка дубликатов

Ищут и объединяют дублирующиеся записи CRM

Сквозная аналитика

Создают трейсы и привязывают объекты CRM к источникам обращения

История движения по стадиям

Возвращает историю перемещения элементов по стадиям

Предыдущая версия API

Для поддержки существующих интеграций сохранены универсальные методы crm.item.*, методы сделок, лидов, контактов, компаний и предложений, реквизиты, справочники crm.status.* и вспомогательные объекты. Они собраны в разделе Предыдущая версия API.