Выбор API CRM зависит от того, где выполняется код и с какими данными он работает. Код внутри коробочного Битрикс24 может вызывать локальный PHP API. Внешнее приложение обращается к порталу через REST. В локальном коде способ работы зависит от задачи. Чтобы изменить поля сделки, добавить к ней товары и запланировать звонок, нужны разные объекты API.

Определить, где выполняется код

Коробочный Битрикс24 работает в отдельной установке. Ее серверный код может обращаться к локальному PHP API модуля crm. Такой код может выполняться в обработчике события, компоненте или фоновом задании. Чтобы использовать классы CRM в этом коде, сначала подключите модуль crm.

Для облачного Битрикс24 используйте REST API Битрикс24. Через REST работает и приложение на другом сервере, потому что оно не может напрямую вызвать PHP-классы портала. В коробочном Битрикс24 выбор зависит от места запуска кода. Внутри установки доступен локальный PHP API, извне — REST.

Если код обмена с внешней системой запускается внутри коробочного портала, он тоже может использовать локальный PHP API. Такой код получает данные из внешней системы и сохраняет их в CRM. Как организовать обмен, читайте в статье Синхронизация CRM с внешней системой.

Выбрать API по задаче

Для чтения и изменения основных элементов CRM начните с фабрики типа. Контейнер Bitrix\Crm\Service\Container возвращает ее по entityTypeId — идентификатору типа CRM, а не ID отдельной записи. Если контейнер вернул null, проверьте идентификатор и поддержку фабрики. Для типа без фабрики используйте отдельный API объекта.

Чтобы разобраться, как связаны тип, фабрика, элемент и операция, откройте статью Схема работы CRM и основные объекты API.

Выбор зависит и от того, что именно нужно изменить. Данные элемента, его связи и связанные объекты CRM могут иметь разные способы сохранения.

Допустим, обработчик внутри коробочного портала должен изменить название сделки, обновить ее товары и запланировать звонок. Получите сделку через фабрику, измените название и товарные позиции у ее элемента, затем сохраните изменения операцией. Для звонка создайте отдельное дело и привяжите его к сделке. Так вы выберете API для каждого результата, который должен появиться в CRM.

Адрес клиента или связь сделки с контактом тоже требуют выбора способа работы с соответствующими данными. Изменение одного поля сделки может не выполнить такую задачу.

|

|| Задача | С чего начать || || Прочитать лид, сделку, контакт, компанию, коммерческое предложение, счет или элемент смарт-процесса | Получите фабрику типа. Если результат нужно показать пользователю, выбирайте записи с учетом его прав. Работа с элементами CRM || || Создать, изменить или удалить элемент | Получите операцию фабрики, запустите ее и проверьте результат. Подробные сценарии: создание, изменение, удаление || || Изменить направление или стадию | Проверьте, поддерживает ли их фабрика типа, затем выберите допустимое значение и сохраните элемент операцией. Направления и стадии || || Изменить телефоны, email, адреса или реквизиты | Выберите API для конкретного вида данных. Не все эти данные хранятся как обычные поля элемента. Поля и данные клиента || || Привязать клиентские записи или другие элементы CRM | Определите вид связи и используйте соответствующий способ ее изменения. Связи между элементами || || Добавить или изменить товарные позиции | Проверьте, поддерживает ли тип товары, измените позиции у элемента и сохраните его операцией фабрики. Товары в элементах CRM || || Запланировать звонок или встречу | Создайте дело и привяжите его к элементу CRM через API дел. Дела и история взаимодействий || || Проверить доступ сотрудника | Для чтения примените выборку с учетом прав, для записи задайте пользователя в контексте операции. Права доступа в PHP API CRM || || Выполнить действие при изменении элемента | Выберите событие или другой способ подключить свой код с учетом момента его вызова. События и расширение поведения CRM || || Работать с заказом, оплатой или отгрузкой | Используйте API заказа CRM и модуля sale. Фабрика заказа не дает общего набора операций для этих действий. Интернет-магазин || |#

Когда фабрика недоступна

Метод Container::getFactory() возвращает фабрику или null. Поддержка зависит от типа.

|

|| Тип | Фабрика через Container::getFactory() | Условие и способ работы || || Лид, сделка, контакт, компания, коммерческое предложение | Да | Используйте общую модель фабрики || || Созданный смарт-процесс | Да | Тип должен существовать в CRM || || SmartInvoice, SmartDocument, SmartB2eDocument | Да | Используйте фабрику соответствующего типа || || Заказ | Ограниченно | Нужен модуль sale. Через фабрику нельзя прочитать, создать, изменить или удалить заказ. Используйте API заказа CRM и Интернет-магазина || || Дело, реквизит | Нет | Используйте отдельные классы и сервисы объекта || |#

Учесть различия типов

Для готового типа используйте его константу CCrmOwnerType. У пользовательского смарт-процесса возьмите entityTypeId созданного типа. Не вычисляйте этот идентификатор по имени или диапазону чисел. Узнать, как найти и настроить тип, можно в статье Смарт-процессы.

Для счета выбирайте CCrmOwnerType::SmartInvoice. По этой константе контейнер находит фабрику счета. Она читает счета, а ее операции сохраняют изменения.

Возможности фабрики зависят от типа CRM. У одних типов есть направления и стадии, у других — только часть этих возможностей. Товары, клиентские связи и другие данные тоже зависят от типа и его настроек. Перед использованием возможности проверьте, поддерживает ли ее фабрика выбранного типа. Так вы не заложите в сценарий работу со стадиями, товарами или связями, если тип их не поддерживает. Затем выберите профильную статью из таблицы выше.

Поддерживать код на классическом API

Помимо фабрик, в существующем PHP-коде встречаются классы вида CCrm..., например CCrmContact. Работа через такие классы относится к классическому API. Не переписывайте рабочий сценарий только ради замены названий классов. Сначала выясните, какие данные он читает, какие меняет и какие связанные действия ожидает после записи.

Для нового сценария с элементами, у которых есть фабрика, используйте ее операции. Они проверяют данные и права, сохраняют элемент и выполняют связанные действия. Порядок сохранения и проверки результата приведен в статье Схема работы CRM и основные объекты API.

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

Если задача касается отдельного объекта, например реквизита или дела, используйте его профильный API. Выбор фабрики основного элемента сам по себе не заменяет работу с этими объектами.