REST: смарт-процессы (crm.item)

Смарт-процессы — это пользовательские CRM-сущности Битрикс24 со своими полями, воронками и автоматизацией. Управляются они универсальным семейством crm.item.*, а сами типы создаются через crm.type.*.

Что такое смарт-процесс и entityTypeId

Смарт-процесс (СПА, smart process automation) позволяет завести собственную сущность — например «Договоры» или «Заявки на сервис» — не программируя модуль. У неё есть карточка, стадии, права и роботы, как у сделки.

Ключевое понятие универсального API — entityTypeId, числовой идентификатор типа сущности:

Смарт-процессы появились как замена устаревшим «пользовательским разделам» и лид-сделочной жёсткой схеме. Они дают гибкость: вы описываете сущность декларативно в интерфейсе, а через REST получаете полноценный CRUD без единой строки серверного кода на портале. Точный entityTypeId нового процесса узнаётся из ответа crm.type.add или списка crm.type.list.

Создание типа: crm.type

Сам смарт-процесс (его тип) создаётся и настраивается семейством crm.type.*:

• crm.type.add — создать тип смарт-процесса;
• crm.type.list — список типов и их entityTypeId;
• crm.type.get / update / delete.

Пример: { "fields": { "title": "Договоры", "isCategoriesEnabled": "Y", "isStagesEnabled": "Y", "isPaymentsEnabled": "N" } }. В ответе придёт объект типа, из которого вы возьмёте entityTypeId для дальнейших вызовов crm.item.*.

Флаги в настройках типа включают отдельные подсистемы: isStagesEnabled — канбан со стадиями, isCategoriesEnabled — несколько воронок, isPaymentsEnabled — товары и оплаты, isClientEnabled — привязку контактов и компаний. От этих флагов зависит, какие поля и под-методы станут доступны у элементов процесса, поэтому продумать их лучше сразу.

Создание элемента: crm.item.add

Элемент смарт-процесса создаётся так же, как любая сущность, но с обязательным entityTypeId:

{ "entityTypeId": 130, "fields": { "title": "Договор №77", "stageId": "DT130_1:NEW", "opportunity": 90000, "assignedById": 1, "ufCrm5_1690000000": "доп. значение" } }

Выборка: crm.item.list

Метод crm.item.list принимает entityTypeId и знакомые параметры filter, select, order, start. Результат приходит в объекте items.

{ "entityTypeId": 130, "filter": { "stageId": "DT130_1:NEW" }, "select": ["id","title","opportunity"], "order": { "id": "DESC" } }

Пагинация — те же 50 элементов на страницу; для быстрого перебора применяйте start: -1 и листание по id.

Фильтр и сортировка работают по тем же префиксам операторов, что и в crm.deal.list, только имена полей — в camelCase. Пользовательские поля смарт-процесса тоже участвуют в фильтре, но их нужно явно перечислять в select, иначе они не попадут в ответ. Результат всегда завёрнут в ключ items, а не выдаётся плоским массивом, как у старых методов.

Изменение и удаление

Обновление и удаление симметричны:

• crm.item.update — { entityTypeId, id, fields };
• crm.item.get — { entityTypeId, id };
• crm.item.delete — { entityTypeId, id };
• crm.item.fields — описание всех полей типа, включая пользовательские.

Перед интеграцией всегда вызывайте crm.item.fields для нужного entityTypeId — только он покажет реальные имена пользовательских полей вида ufCrm5_XXX.

Обновление работает как частичное: в fields передаются только меняемые поля, остальные сохраняют прежние значения. Это удобно для точечной синхронизации статуса или суммы. Метод crm.item.update также умеет двигать элемент по стадиям — достаточно передать новый stageId, и сработает та же автоматизация, что и у сделок.

Стадии, товары и привязки

У смарт-процесса могут быть включены воронки, стадии и товарные позиции. Работают знакомые механизмы, но через универсальные методы:

• стадии — crm.status.list с ENTITY_ID вида DYNAMIC_130_STAGE_N;
• воронки — crm.category.list с entityTypeId смарт-процесса;
• товары — crm.item.productrow.* (add/set/list/get/delete);
• привязки к другим сущностям — через поля-связи или родительские parentId.

Смарт-процесс можно сделать дочерним к сделке или другому процессу: тогда в его элементах появляется поле-связь parentId{entityTypeId}, через которое элемент прикрепляется к родителю. Это удобно для сценариев вроде «у сделки несколько отгрузок» или «у договора несколько актов». Права доступа к смарт-процессу настраиваются отдельно от сделок, поэтому вебхук или приложение должны иметь доступ именно к нужному типу, иначе вызовы crm.item.* вернут ошибку доступа даже при корректном entityTypeId.

Итог

Смарт-процессы через crm.type.* и crm.item.* — гибкий способ завести в CRM любую бизнес-сущность без разработки модуля. Главное — держать в голове entityTypeId, помнить про camelCase-имена полей и особый формат идентификаторов стадий.

Мы в B2Bsite проектируем смарт-процессы под реальные процессы — договоры, заявки, согласования — и связываем их через API с сайтом и учётными системами. Если стандартных сущностей CRM не хватает, поможем смоделировать нужную и автоматизировать её.