Схема работы CRM и основные объекты API

API CRM работает с записью через ее тип. Сервисный контейнер Bitrix\Crm\Service\Container возвращает фабрику для выбранного типа. Фабрика загружает элемент, а операция проверяет и сохраняет изменения.

Назначение лидов, сделок, контактов и других объектов описано в статье Введение в CRM.

Основные элементы CRM

Основные элементы CRM описывают клиента и работу с продажей. Для большинства из них CRM предоставляет общую модель Factory → Item → Operation.

Объект

Для чего нужен

Идентификатор типа

Лид

Еще не квалифицированное обращение

CCrmOwnerType::Lead

Контакт

Человек, с которым работает компания

CCrmOwnerType::Contact

Компания

Организация-клиент

CCrmOwnerType::Company

Сделка

Работа над отдельной продажей

CCrmOwnerType::Deal

Коммерческое предложение

Предложение клиенту с условиями продажи

CCrmOwnerType::Quote

Счет

Расчеты с клиентом

CCrmOwnerType::SmartInvoice

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

Настраиваемый бизнес-объект

Собственный entityTypeId

Заказ

Оформленная покупка

CCrmOwnerType::Order

Фабрика заказа не предоставляет общий набор операций чтения и изменения заказа. Для работы с ним используйте API заказа CRM и модуля sale.

Другие идентификаторы CRM

В CCrmOwnerType есть типы для отдельных механизмов CRM и смежных модулей.

Группа

Константы CCrmOwnerType

Назначение

Повторяющиеся операции

CCrmOwnerType::DealRecurring

Повторяющиеся сделки

Работа с делами

CCrmOwnerType::Wait, CCrmOwnerType::CallList, CCrmOwnerType::CustomActivityType

Ожидания, списки обзвона и пользовательские типы дел

Оценка и документы

CCrmOwnerType::Scoring, CCrmOwnerType::CopilotCallAssessment, CCrmOwnerType::SmartDocument, CCrmOwnerType::SmartB2eDocument, CCrmOwnerType::AgentContractDocument

Оценка данных и звонков, специализированные документы

Заказы и склад

CCrmOwnerType::OrderCheck, CCrmOwnerType::CheckCorrection, CCrmOwnerType::OrderPayment, CCrmOwnerType::OrderShipment, CCrmOwnerType::DeliveryRequest, CCrmOwnerType::StoreDocument, CCrmOwnerType::ShipmentDocument

Чеки, оплаты, отгрузки, доставка и складские документы

Системные операции

CCrmOwnerType::System

Внутренний системный тип

Для элементов в корзине предусмотрены отдельные типы CCrmOwnerType::SuspendedLead, CCrmOwnerType::SuspendedDeal, CCrmOwnerType::SuspendedContact, CCrmOwnerType::SuspendedCompany, CCrmOwnerType::SuspendedQuote, CCrmOwnerType::SuspendedOrder, CCrmOwnerType::SuspendedActivity, CCrmOwnerType::SuspendedRequisite, CCrmOwnerType::SuspendedSmartInvoice, CCrmOwnerType::SuspendedSmartDocument и CCrmOwnerType::SuspendedSmartB2eDocument. Для элементов динамических типов в корзине также используются отдельные идентификаторы.

Эти константы не образуют единый список карточек CRM. Не каждый тип поддерживает фабрику элементов и одинаковый набор операций.

Тип и идентификатор элемента

Числовой ID уникален только в пределах типа. Сделка и контакт с одинаковым ID — разные элементы. Для ссылки на запись храните entityTypeId вместе с ID элемента.

Объект ItemIdentifier объединяет эти значения. Метод ItemIdentifier::createByItem() создает идентификатор из загруженного элемента и при необходимости добавляет ID категории.

Метод ItemIdentifier::createByParams() проверяет идентификатор типа и требует положительный ID элемента. При неверных значениях метод возвращает null. Такая проверка не ищет запись и не проверяет наличие фабрики.

Для пары «сделка, ID 123» запросите фабрику CCrmOwnerType::Deal. Для пары «контакт, ID 123» нужна фабрика CCrmOwnerType::Contact. По одному числовому ID выбрать фабрику нельзя.

Категории, направления и стадии

В типах с направлениями категория задает направление. Направление содержит собственный набор стадий, а стадия показывает положение элемента в процессе.

Значения идентификаторов имеют разное назначение.

  • entityTypeId — тип элемента.

  • ID — элемент внутри типа.

  • ID категории — категория или направление для типа, который поддерживает направления.

  • ID стадии — положение элемента в процессе.

Возможности зависят от типа и его настроек.

Метод фабрики

Что проверяет

isCategoriesSupported()

Поддерживает ли тип категории

isStagesSupported()

Поддерживает ли тип стадии

isStagesEnabled()

Доступны ли стадии для выбранного типа с учетом его настроек

Проверяйте эти методы перед работой с категориями и стадиями. Не переносите значения и настройки со сделки на контакт или смарт-процесс без проверки. Для выбора направления и перехода элемента используйте статью Направления и стадии.

Объекты для работы с элементом

Объекты отвечают за выбор типа, загрузку записи, изменение полей и сохранение.

Объект

Что делает

Что возвращает

CCrmOwnerType

Содержит идентификаторы готовых типов CRM

entityTypeId

Bitrix\Crm\Service\Container

Возвращает сервисы CRM и фабрику по entityTypeId

Объект Factory или null

Bitrix\Crm\Service\Factory

Читает элементы своего типа, создает объекты в памяти и формирует операции

Item, список элементов или Operation

Bitrix\Crm\Item

Хранит поля одного элемента, его тип и ID

Значения полей в памяти

Bitrix\Crm\Service\Context

Задает пользователя, от имени которого выполняется операция

Контекст для операции

Bitrix\Crm\Service\Operation

Проверяет данные и права, сохраняет элемент и запускает разрешенные действия CRM

Bitrix\Main\Result

Bitrix\Main\Result

Хранит ошибки и данные, которые вернула операция

Признак успеха и список ошибок

Bitrix\Crm\ItemIdentifier

Хранит тип и ID конкретного элемента, при необходимости — ID категории

Составной идентификатор элемента

Bitrix\Crm\RelationIdentifier

Хранит типы родителя и потомка

Описание направления связи между типами

Объекты образуют последовательный маршрут от типа к результату операции.

entityTypeId → Container → Factory
                           ├─ getItem() / createItem() → Item
                           └─ getAddOperation() / getUpdateOperation()
                              / getDeleteOperation() → Operation → Result

Порядок работы с элементом

Для типа с фабрикой используйте один маршрут.

  1. Определите entityTypeId.

  2. Получите фабрику через Container::getFactory(). Метод возвращает объект Factory или null, поэтому проверьте результат.

  3. Загрузите элемент через getItem() или создайте объект через createItem().

  4. Задайте значения полей через методы Item.

  5. Получите операцию добавления, изменения или удаления.

  6. Вызовите launch().

  7. Проверьте Result.

Метод getItem($id) возвращает элемент или null, а getItems() — список элементов. Эти методы не отбирают записи по правам пользователя. Полные примеры чтения, создания, изменения и удаления приведены в статье Работа с элементами CRM.

Проверить права на чтение и изменение

Для чтения с учетом прав используйте getItemsFilteredByPermissions(). Передайте действие, фильтр по ID и ID пользователя. Пустой результат может означать, что запись не существует или пользователь не может ее прочитать.

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

Чтобы выполнить операцию от имени конкретного пользователя, задайте его ID через Context::setUserId() и передайте контекст в метод получения операции. Для фонового задания контекст нужно задавать явно, если у задания нет подходящего текущего пользователя. Предварительные проверки и запуск операции с контекстом приведены в статье Права доступа в PHP API CRM.

Как операция сохраняет изменения

Метод Item::set() меняет значение только в памяти. Запись сохраняет операция.

Операция выполняет этапы в таком порядке.

  1. Проверяет ограничения, права, поля и действия перед сохранением.

  2. Сохраняет элемент.

  3. Обрабатывает разрешенные связанные данные и действия после сохранения.

  4. В зависимости от типа и настроек обновляет историю и таймлайн, запускает бизнес-процессы и автоматизацию.

  5. Возвращает Result.

Ошибка после сохранения не отменяет уже записанные данные. Успешный Result не подтверждает, что бизнес-процессы и автоматизация завершились успешно.

В примере сделка уже прочитана с учетом прав и доступна в $deal. Ее фабрика находится в $factory, а ID пользователя — в $userId.

$deal->set(\Bitrix\Crm\Item::FIELD_NAME_TITLE, 'Новое название');
$context = (new \Bitrix\Crm\Service\Context())->setUserId($userId);
$result = $factory->getUpdateOperation($deal, $context)->launch();

if (!$result->isSuccess())
{
    throw new \RuntimeException(implode('; ', $result->getErrorMessages()));
}

Полный сценарий с получением фабрики и проверкой прав приведен в статье Работа с элементами CRM.

Проверить результат операции

Ошибка может возникнуть до сохранения или после него. Result не содержит универсального номера этапа, поэтому учитывайте текст ошибки и текущее состояние элемента.

Результат

Состояние элемента

Следующее действие

Ошибка до сохранения

Операция не дошла до сохранения

Исправить данные или права и повторить операцию

Ошибка при сохранении или после него

Часть данных уже могла измениться

Перечитать элемент и определить, какую часть действия нужно повторить

Успех без изменений

Операция могла завершиться до сохранения и связанных действий

Не ожидать повторного запуска истории, автоматизации или других действий CRM

Успех после сохранения

В Result нет ошибок, которые добавила операция

Проверить сохраненные данные, если от них зависит ответ внешней системе

Если поля не изменились, Operation\Update::isItemChanged() возвращает false. Такая операция завершается успешно до сохранения и последующих действий.

Результаты запуска бизнес-процессов и автоматизации не добавляются в Result, который возвращает Operation::launch().

Повторить действие после ошибки

Перед повтором перечитайте элемент: ошибка могла возникнуть после записи, а повторное создание — добавить дубль. Сравнение сохраненных значений перед повторным изменением приведено в статье Работа с элементами CRM. Для разбора ошибок и выбора незавершенного действия используйте статью Производительность и типовые ошибки CRM.

Системные поля элементов CRM

В CRM состав полей определяет фабрика выбранного типа. Метод Factory::getFieldsInfo() возвращает описания системных полей, а Factory::getFieldsCollection() добавляет к ним пользовательские поля. Для получения описаний, проверки обязательности и подготовки значений используйте статью Поля и данные клиента.

В таблицах указаны общие имена. Фабрика может сопоставить их с другими именами хранения. Например, у лида STAGE_ID соответствует STATUS_ID, а CREATED_TIME — DATE_CREATE.

Базовые поля фабричной модели

Эти имена используются в нескольких фабриках. Фактическое наличие поля проверяйте по коллекции полей конкретного типа.

Поле

Тип данных

Описание

ID

integer

Идентификатор элемента. Поле формирует CRM, изменить его нельзя

TITLE

string

Название элемента. У контакта вместо названия используются поля имени

ASSIGNED_BY_ID

user

Ответственный пользователь

OPENED

boolean

Признак доступности элемента другим пользователям

CREATED_BY

user

Пользователь, который создал элемент. Поле только для чтения

UPDATED_BY

user

Пользователь, который последним изменил элемент. Поле только для чтения

CREATED_TIME

datetime

Дата и время создания. Поле только для чтения

UPDATED_TIME

datetime

Дата и время последнего изменения. Поле только для чтения

COMMENTS

text

Комментарий. Для готовых типов обычно содержит BB-код

OBSERVERS

user, multiple

Наблюдатели. Поле есть у типов с поддержкой наблюдателей

WEBFORM_ID

crm_webform или integer

CRM-форма, которая создала элемент. Тип и ограничения зависят от фабрики

LAST_ACTIVITY_BY

user

Пользователь последней активности в таймлайне, если тип поддерживает эти данные

LAST_ACTIVITY_TIME

datetime

Дата и время последней активности в таймлайне, если тип поддерживает эти данные

LAST_COMMUNICATION_TIME

string

Время последней коммуникации. Поле только для чтения

ORIGINATOR_ID

string

Идентификатор внешней системы

ORIGIN_ID

string

Идентификатор элемента во внешней системе

ORIGIN_VERSION

string

Версия данных во внешней системе, если фабрика поддерживает это поле

У лида WEBFORM_ID имеет тип integer. У сделки это поле имеет тип crm_webform: значение можно задать при создании, но нельзя изменить после него.

Поля подключаемых возможностей

Фабрика добавляет эти поля только тогда, когда тип поддерживает соответствующую возможность.

Поле

Тип данных

Когда появляется и что хранит

CATEGORY_ID

crm_category

Категория элемента. Для типов с направлениями определяет направление

STAGE_ID

crm_status

Текущая стадия элемента

PREVIOUS_STAGE_ID

crm_status

Предыдущая стадия. Поле только для чтения

MOVED_BY

user

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

MOVED_TIME

datetime

Дата и время последнего изменения стадии. Поле только для чтения

BEGINDATE

date

Дата начала, если для типа включены начальная и конечная даты

CLOSEDATE

date

Планируемая или фактическая дата завершения

COMPANY_ID

crm_company

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

CONTACT_ID

crm_contact

Основной контакт. Устаревшее одиночное поле. Для нескольких контактов используйте связи

CONTACT_IDS

crm_contact, multiple

Идентификаторы связанных контактов

CONTACTS

crm_contact, multiple

Объекты связанных контактов

MYCOMPANY_ID

crm_company

Компания, от имени которой ведется продажа

CURRENCY_ID

crm_currency

Валюта суммы элемента

EXCH_RATE

double

Курс валюты у готовых типов. Динамические элементы не содержат это поле

PRODUCT_ROWS

crm_product_row, multiple

Товарные позиции. В Item этому имени соответствует FIELD_NAME_PRODUCTS

OPPORTUNITY

double

Сумма элемента в CURRENCY_ID

TAX_VALUE

double

Сумма налога в валюте элемента

ACCOUNT_CURRENCY_ID

crm_currency

Валюта учета. Поле только для чтения

OPPORTUNITY_ACCOUNT, TAX_VALUE_ACCOUNT

double

Сумма элемента и налог в валюте учета. Поля только для чтения

IS_MANUAL_OPPORTUNITY

boolean

Признак ручного расчета суммы

SOURCE_ID

crm_status

Источник элемента, если тип поддерживает источники

SOURCE_DESCRIPTION

text

Дополнительные сведения об источнике

IS_RECURRING

boolean

Признак регулярного элемента, если тип поддерживает повторение

Поля готовых типов

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

Лид

Поле

Тип данных

Описание

HONORIFIC

crm_status

Обращение к клиенту

NAME, SECOND_NAME, LAST_NAME, POST

string

Части имени и должность клиента

FULL_NAME

string

Полное имя, которое формирует CRM. Только для чтения

BIRTHDATE

date

Дата рождения

BIRTHDAY_SORT

integer

Служебное значение сортировки по дню рождения. Только для чтения

COMPANY_TITLE

string

Название компании, указанное непосредственно в лиде

STATUS_DESCRIPTION

text

Дополнительные сведения о стадии

DATE_CLOSED

datetime

Дата завершения лида. Только для чтения

STAGE_SEMANTIC_ID

string

Семантика стадии. Только для чтения

IS_RETURN_CUSTOMER

boolean

Признак повторного лида. Только для чтения

HAS_PHONE, HAS_EMAIL, HAS_IMOL

boolean

Признаки способов связи, которые формирует CRM. Только для чтения

FM

crm_multifield, multiple

Телефоны, email, мессенджеры и другие способы связи

Сделка

Поле

Тип данных

Описание

TYPE_ID

crm_status

Тип сделки

PROBABILITY

integer

Вероятность успешного завершения в процентах

STAGE_SEMANTIC_ID

string

Семантика стадии. Только для чтения

IS_RETURN_CUSTOMER

boolean

Признак повторной сделки. Только для чтения

IS_NEW, IS_REPEATED_APPROACH

boolean

Признаки новой сделки и повторного обращения. Только для чтения

CLOSED

boolean

Признак закрытой сделки. Только для чтения

QUOTE_ID

crm_quote

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

LEAD_ID

crm_lead

Лид, из которого создана сделка

ADDITIONAL_INFO

string

Дополнительная информация

LOCATION_ID

location

Местоположение

REPEAT_SALE_SEGMENT_ID

crm_repeat_sale_segment_title, multiple

Сценарии повторной продажи. Только для чтения, если функция доступна пользователю

Контакт

Поле

Тип данных

Описание

HONORIFIC

crm_status

Обращение

NAME, SECOND_NAME, LAST_NAME, POST

string

Части имени и должность

FULL_NAME

string

Полное имя, которое формирует CRM. Только для чтения

PHOTO

file

Фотография

BIRTHDATE

date

Дата рождения

BIRTHDAY_SORT

integer

Служебное значение сортировки по дню рождения. Только для чтения

TYPE_ID

crm_status

Тип контакта

EXPORT

boolean

Признак экспорта

COMPANY_ID

crm_company

Устаревшее поле основной компании

COMPANY_IDS, COMPANIES

crm_company, multiple

Идентификаторы и объекты связанных компаний

LEAD_ID

crm_lead

Лид, из которого создан контакт

HAS_PHONE, HAS_EMAIL, HAS_IMOL

boolean

Признаки способов связи, которые формирует CRM. Только для чтения

FM

crm_multifield, multiple

Телефоны, email, мессенджеры и другие способы связи

Компания

Поле

Тип данных

Описание

TYPE_ID

crm_status

Тип компании

INDUSTRY

crm_status

Сфера деятельности

EMPLOYEES

crm_status

Диапазон количества сотрудников

LOGO

file

Логотип

REVENUE

double

Годовой оборот в CURRENCY_ID

IS_MY_COMPANY

boolean

Признак собственной компании. Задается при создании и затем не изменяется

CONTACT_IDS, CONTACTS

crm_contact, multiple

Идентификаторы и объекты связанных контактов

LEAD_ID

crm_lead

Лид, из которого создана компания

HAS_PHONE, HAS_EMAIL, HAS_IMOL

boolean

Признаки способов связи, которые формирует CRM. Только для чтения

FM

crm_multifield, multiple

Телефоны, email, мессенджеры и другие способы связи

BANKING_DETAILS

text

Устаревшее поле. Используйте API реквизитов и банковских реквизитов

Коммерческое предложение

Поле

Тип данных

Описание

QUOTE_NUMBER

string

Уникальный номер, который формирует CRM

CONTENT

text

Содержание предложения в формате BB-кода

TERMS

text

Условия предложения в формате BB-кода

DEAL_ID

crm_deal

Связанная сделка

LEAD_ID

crm_lead

Связанный лид

STORAGE_TYPE_ID

integer

Тип хранилища файлов

STORAGE_ELEMENT_IDS

integer, multiple

Идентификаторы файлов в хранилище

PERSON_TYPE_ID

integer

Тип плательщика. Только для чтения

ACTUAL_DATE

date

Дата, до которой предложение актуально

LOCATION_ID

location

Местоположение

CLOSED

boolean

Признак завершенного предложения. Только для чтения

Счет

Поле

Тип данных

Описание

ACCOUNT_NUMBER

string

Уникальный номер счета, который формирует CRM

COMMENTS

text

Комментарий в формате BB-кода

LOCATION_ID

location

Местоположение

Счет наследует динамический элемент. Для предустановленного типа включены стадии, начальная и конечная даты, клиент, товары, своя компания, источник, наблюдатели и повторение. Направления выключены в интерфейсе, но CATEGORY_ID остается в модели, поскольку динамический тип поддерживает категории на уровне API.

Способы связи и привязки клиентов

Поле FM содержит способы связи контакта или компании. В Item оно представлено объектом Bitrix\Crm\Multifield\Collection. Телефоны, email и другие значения хранятся отдельно от основной записи элемента.

Связи между контактами и компаниями также хранятся отдельно от основных записей.

Объект

Основная связь

Идентификаторы всех связей

Привязки

Связанные объекты

Контакт

COMPANY_ID — основная компания

COMPANY_IDS

COMPANY_BINDINGS

COMPANIES

Компания

Нет отдельного поля

CONTACT_IDS

CONTACT_BINDINGS

CONTACTS

Поля смарт-процесса

Смарт-процесс всегда содержит ID, TITLE, XML_ID, поля создания и изменения, ответственного, OPENED, WEBFORM_ID, LAST_COMMUNICATION_TIME и CATEGORY_ID. Остальные группы зависят от настроек типа и доступности функций.

Настройка типа

Какие поля добавляет

Начальная и конечная даты

BEGINDATE, CLOSEDATE

Стадии

STAGE_ID, PREVIOUS_STAGE_ID, MOVED_BY, MOVED_TIME

Клиент

COMPANY_ID, CONTACT_ID, CONTACT_IDS, CONTACTS

Наблюдатели

OBSERVERS

Источник

SOURCE_ID, SOURCE_DESCRIPTION

Товары

CURRENCY_ID, ACCOUNT_CURRENCY_ID, IS_MANUAL_OPPORTUNITY, PRODUCT_ROWS, OPPORTUNITY, TAX_VALUE, OPPORTUNITY_ACCOUNT, TAX_VALUE_ACCOUNT

Собственная компания

MYCOMPANY_ID

Последняя активность

LAST_ACTIVITY_BY, LAST_ACTIVITY_TIME, если поля есть в схеме

Повторение

IS_RECURRING, если повторение включено и доступно

Публичный набор может также содержать поля родительских связей вида PARENT_ID_* и пользовательские поля. При включенном учете коммуникаций появляются LAST_COMMUNICATION_CALL_TIME, LAST_COMMUNICATION_EMAIL_TIME, LAST_COMMUNICATION_IMOL_TIME и LAST_COMMUNICATION_WEBFORM_TIME. Для коммерческого предложения фабрика добавляет UTM_SOURCE, UTM_MEDIUM, UTM_CAMPAIGN, UTM_CONTENT и UTM_TERM.

Перед чтением или записью проверяйте фактическую коллекцию выбранной фабрики. Статический список из этой статьи не заменяет Factory::getFieldsCollection(). Чтобы включить нужные возможности типа, выполните настройку по статье Смарт-процессы.

Связанные данные и границы модулей

Карточка CRM объединяет поля элемента и отдельные связанные записи. Сначала определите, какой объект хранит нужное значение.

Данные

Где менять

Что учесть

Компания и контакты

В полях поддерживающего типа или в отдельных связях между элементами

Проверьте наличие полей COMPANY_ID и CONTACT_BINDINGS у выбранного типа

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

В строках элемента, если фабрика поддерживает Item::FIELD_NAME_PRODUCTS (PRODUCT_ROWS)

Товар, цены и остатки относятся к модулю catalog

Телефоны и email

В поле FM контакта, компании или другого поддерживающего типа

Не заменяйте способы связи реквизитами клиента

Дела

В отдельных записях взаимодействий

Изменение поля элемента не создает и не завершает дело

История и таймлайн

В записях событий, связанных с элементом

Их состав зависит от типа и настроек операции

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

В собственных записях со своими правилами

Не обрабатывайте их как обычные строковые поля сделки

Объект RelationIdentifier задает типы родителя и потомка. ItemIdentifier указывает на конкретный элемент. Для создания связи нужны типы участников и ID самих элементов.

Операция элемента может обновить связанные механизмы CRM, но не превращает каждую связанную запись в поле Item. Для документа используйте API модуля Генератор документов, а для заказа — API модуля Интернет-магазин.

Как определить объект для каждого изменения

Например, нужно изменить название сделки, телефон контакта и сформировать документ.

  1. Измените название в Item сделки через операцию ее фабрики.

  2. Получите фабрику контакта и измените его поле FM.

  3. После изменений в CRM вызовите API documentgenerator.

Проверяйте результат каждого действия отдельно. Успешное изменение сделки не подтверждает изменение контакта или создание документа. Перед повтором перечитайте затронутые записи, чтобы не выполнять уже завершенную часть задания еще раз.

Предыдущая
Введение в CRM
Следующая
Как выбрать API CRM