crm.item.add и crm.item.update: создание и правка смарт-процессов Битрикс24

Работаю с Битрикс24 на проектах, где типовых сделок и лидов уже не хватает: у клиента своя воронка ремонта техники, доставки грузов или документооборота с подрядчиками. Такие сущности заводятся как смарт-процессы, и создать в них новый элемент через API можно только одним способом, методом crm.item.add. Правка уже созданного элемента идёт через crm.item.update. Показываю, как собрать оба запроса на реальных примерах, откуда брать entityTypeId и коды полей, и на каких местах чаще всего спотыкаются те, кто первый раз подключает смарт-процесс к внешней системе.

Смарт-процессы Битрикс24 и место crm.item.add среди методов CRM

Смарт-процесс в Битрикс24 - это пользовательский тип сущности CRM, который создаётся через конструктор в разделе CRM и получает собственную таблицу, воронку со стадиями и набор полей. В отличие от сделок и лидов, у смарт-процессов нет отдельных методов вида crm.deal.add или crm.lead.add. Для работы с любым элементом любого смарт-процесса Битрикс24 использует один универсальный набор методов: crm.item.add, crm.item.update, crm.item.get, crm.item.list и crm.item.delete.

Через эти же методы технически можно работать и со сделками, но для системных сущностей обычно удобнее их собственные методы вроде crm.deal.add. А вот для смарт-процессов crm.item.* - единственный путь, отдельных crm.spa.add или похожих методов в API нет.

На практике я подключаю смарт-процессы через crm.item.add, когда клиенту нужно завести заявку из формы на сайте, сообщение из телеграм-бота или строку из внешней учётной системы сразу в нужную воронку, минуя ручной ввод менеджером. Типичные примеры из моих проектов: заявки на ремонт техники с привязкой к серийному номеру устройства, заказы на доставку с отдельной воронкой под каждый транспортный статус, брони переговорных или оборудования с полями даты и ответственного.

entityTypeId и коды полей: что узнать до вызова crm.item.add

Первое, что нужно перед первым запросом, это entityTypeId смарт-процесса. Это числовой идентификатор конкретного типа сущности, без него ни add, ни update не отработают. Получить список всех типов вместе с их entityTypeId можно методом crm.type.list.

curl -X POST \
  https://ваш-портал.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxxx/crm.type.list.json

У пользовательских смарт-процессов entityTypeId начинается с 1030 и растёт с каждым новым типом, который создают в интерфейсе. Системные сущности используют зарезервированные номера ниже (сделка, лид, контакт, компания), их через crm.item.add обычно не трогают.

Второе, что нужно выяснить, это точные коды полей. У смарт-процесса есть системные поля вроде title, stageId, categoryId, assignedById, opened, а есть пользовательские, которые администратор добавил через интерфейс. Имена пользовательских полей не угадываются по аналогии с другим проектом, их нужно смотреть методом crm.item.fields с передачей entityTypeId. Метод возвращает список всех полей с их кодами, типами (строка, число, дата, список, сотрудник, привязка к другой сущности CRM) и, для полей типа «список», допустимыми значениями с их числовыми ID. Для полей-справочников в crm.item.add нужно передавать именно ID значения, а не подписанный текст, который видит пользователь в интерфейсе.

Создаю элемент смарт-процесса через crm.item.add

Запрос к crm.item.add идёт методом POST через входящий вебхук или через приложение с OAuth-токеном и правом crm. У входящего вебхука адрес выглядит так: https://ваш-портал.bitrix24.ru/rest/USER_ID/WEBHOOK_CODE/crm.item.add.json. В теле запроса нужны два обязательных параметра: entityTypeId и fields - объект со значениями полей.

curl -X POST \
  https://ваш-портал.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxxx/crm.item.add.json \
  -H "Content-Type: application/json" \
  -d '{
    "entityTypeId": 1058,
    "fields": {
      "title": "Заявка с сайта",
      "stageId": "DT1058_1:NEW",
      "assignedById": 1,
      "opened": "Y"
    }
  }'

Ответ возвращает объект item с полным набором полей, включая присвоенный id, по которому потом обновляю или получаю элемент.

import requests

webhook = "https://ваш-портал.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxxx/"

payload = {
    "entityTypeId": 1058,
    "fields": {
        "title": "Заявка с сайта",
        "stageId": "DT1058_1:NEW",
        "assignedById": 1,
        "opened": "Y"
    }
}

response = requests.post(webhook + "crm.item.add.json", json=payload)
data = response.json()
print(data["result"]["item"]["id"])

Пара нюансов, на которые обращаю внимание в fields: телефон и email передаются не строкой, а массивом объектов с полями VALUE и VALUE_TYPE, дата передаётся в формате YYYY-MM-DD, например 2025-12-28, а дата со временем в формате YYYY-MM-DDThh:mm:ss±hh:mm, например 2023-12-28T14:05:48+03:00, а для полей-справочников нужен числовой ID значения, о котором говорил выше. Если поле вообще не указать, Битрикс24 подставит значение по умолчанию из настроек смарт-процесса или оставит его пустым.

crm.item.update: правка полей и смена стадии элемента

Для обновления уже существующего элемента нужны entityTypeId, id элемента и fields с теми полями, которые меняются. Остальные поля трогать не нужно: crm.item.update обновляет только переданные значения, а не перезаписывает элемент целиком.

import requests

webhook = "https://ваш-портал.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxxx/"

payload = {
    "entityTypeId": 1058,
    "id": 42,
    "fields": {
        "stageId": "DT1058_1:SUCCESS"
    }
}

response = requests.post(webhook + "crm.item.update.json", json=payload)
print(response.json())

Отдельно про смену стадии. У смарт-процессов идентификатор стадии составной и обычно выглядит как DT{entityTypeId}_{categoryId}:{код стадии}, например DT1058_1:NEW или DT1058_1:SUCCESS. Если в смарт-процессе несколько воронок (категорий), стадия из одной категории не подойдёт для элемента из другой: сначала меняют categoryId, потом stageId с учётом новой категории. Точные коды стадий тоже стоит смотреть через crm.item.fields или прямо в настройках воронки в интерфейсе, а не собирать по аналогии с другими проектами.

Типичные ошибки при работе с crm.item.add и crm.item.update

• Не передан entityTypeId - запрос падает с ошибкой аргумента, метод не понимает, в какой смарт-процесс писать
• Код пользовательского поля угадан по аналогии с другим проектом - у каждого смарт-процесса свой набор кодов, они не переносятся между порталами и даже между разными смарт-процессами одного портала
• В поле-справочник передан текст вместо ID - Битрикс24 либо проигнорирует значение, либо вернёт ошибку валидации, зависит от типа поля
• Стадия передана без учёта категории - элемент остаётся на прежней стадии либо не создаётся вовсе, если DT-префикс не совпадает с entityTypeId
• Вебхук создан без права crm - методы отвечают ошибкой доступа, даже если тот же вебхук нормально работает для других разделов
• Массовая заливка элементов одним потоком без пауз - при импорте на сотни строк Битрикс24 начинает возвращать ошибки очереди запросов, помогает пакетный метод batch или отправка с небольшой задержкой между вызовами

Автоматическое создание элементов: боты, Tilda-формы и n8n

На практике crm.item.add редко вызывают руками, чаще это часть какой-то автоматизации. Например, в телеграм-боте на aiogram после того, как пользователь прошёл диалог и оставил контакты, бот сам делает POST-запрос к вебхуку и заводит заявку сразу в нужном смарт-процессе с проставленной стадией и ответственным.

Форма на Tilda работает похожим образом: она отправляет данные либо напрямую на вебхук Битрикс24 через кастомный скрипт, либо в n8n, где уже собирается нужный объект fields под конкретный entityTypeId и уходит запрос к crm.item.add. Второй вариант удобнее, когда данные перед попаданием в CRM нужно провалидировать, обогатить (например, определить город доставки по индексу) или развести по разным смарт-процессам по условию. Настройку такого моста между формой и Битрикс24 я обычно оформляю как настройка автоматизации в n8n, отдельной услугой на сайте, стоимость такой работы у меня начинается от 25 000 ₽ в зависимости от количества полей и условий маршрутизации.

Отдельная тема, часто идущая рядом, это доработка самого Tilda-сайта под конкретный смарт-процесс: свои поля формы, скрытые параметры, привязка к нужной категории воронки. Такие точечные правки я делаю как кастомный скрипт для Tilda, стоимость начинается от 3 000 ₽. Если же нужна связка посерьёзнее, с несколькими системами и обработкой ошибок на каждом шаге, это уже комплексная интеграция, и её я оцениваю от 40 000 ₽.

Условия и возможности Битрикс24 меняются, поэтому перед запуском я уточняю их у самого сервиса.

Частые вопросы

Чем crm.item.add отличается от crm.deal.add?

crm.item.add - универсальный метод для любых типов CRM-сущностей, включая пользовательские смарт-процессы, и работает через параметр entityTypeId. crm.deal.add жёстко привязан к сделкам и не требует entityTypeId, зато создать через него элемент смарт-процесса нельзя - для этого есть только crm.item.add.

Как узнать entityTypeId своего смарт-процесса?

Вызвать метод crm.type.list без параметров: он вернёт список всех типов сущностей на портале вместе с их entityTypeId и названием. Дальше остаётся найти нужный смарт-процесс по title, который совпадает с названием, заданным в интерфейсе CRM.

Можно ли добавить элемент без указания stageId?

Можно, тогда элемент попадёт на первую стадию воронки по умолчанию для той категории, что настроена в смарт-процессе. Если у смарт-процесса несколько воронок и нужна не первая по счёту стадия, categoryId и stageId лучше указывать явно, иначе элемент уйдёт не туда, где его ждут.

Как обновить только одно поле через crm.item.update, не трогая остальные?

Передать в fields только это поле. crm.item.update не перезаписывает элемент целиком, а применяет только те значения, что пришли в запросе, остальные поля остаются такими же, какими были до вызова.