Работа с crm.item в Битрикс24: методы REST для смарт-процессов

Смарт-процессы в Битрикс24 с точки зрения REST API - это не сделки и не лиды, а отдельный тип CRM-сущности, и работать с ними через crm.deal или crm.lead не получится: для этого Битрикс24 вынес отдельное семейство методов crm.item. Я подключал crm.item в паре проектов, где стандартные воронки не подходили: заявки на ремонт с несколькими этапами согласования, бронирование оборудования, заказы с Tilda с нестандартным статусом оплаты. Ниже разбираю, как эти методы устроены на практике, какие грабли встречаются и как связать смарт-процесс с внешними сервисами вроде n8n, СДЭК или платёжного шлюза.

Зачем в Битрикс24 сделали отдельные методы для смарт-процессов

Смарт-процесс (SPA, Smart Process Automation) - это сущность, которую администратор портала настраивает сам: свои поля, свои стадии, свои связи с контактами и компаниями. У сделок и лидов набор полей фиксирован разработчиками Битрикс24, а у смарт-процесса структуру задаёт пользователь через конструктор. Единого метода crm.deal.add для всех смарт-процессов быть не может: система заранее не знает, какие поля появятся в конкретном процессе завтра.

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

Основные методы crm.item в REST и что они делают

Для веб-хука URL строится по обычной схеме: https://ваш-домен.bitrix24.ru/rest/USER_ID/WEBHOOK_CODE/METHOD.json. Добавление элемента выглядит так:

curl -X POST 
  "https://your-domain.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/crm.item.add.json" 
  -H "Content-Type: application/json" 
  -d '{
    "entityTypeId": 1032,
    "fields": {
      "title": "Заявка №4521",
      "stageId": "DT1032_1:NEW",
      "ufCrm_7_1667211234": "Москва, ул. Ленина 12"
    }
  }'

В ответе придёт объект item с id, полями и стадией stageId. Если entityTypeId указан неверно, Битрикс24 вернёт ошибку INVALID_ENTITY_TYPE_ID, а не молча создаст сделку, и это отличие от старых методов, где похожую ошибку легко пропустить среди десятка кодов из старого CRM-модуля.

Как узнать entityTypeId и коды полей своего смарт-процесса

entityTypeId не показывается в интерфейсе как отдельная настройка, его нужно достать методом crm.type.list, который возвращает все зарегистрированные типы CRM-сущностей аккаунта, включая пользовательские смарт-процессы. У каждого типа в ответе есть entityTypeId и title, по названию легко сопоставить нужный процесс.

Дальше вызывается crm.item.fields с этим entityTypeId, метод возвращает список полей: системные (id, title, stageId, assignedById) и пользовательские, у которых префикс ufCrm с автогенерированным числовым хвостом вроде ufCrm_7_1667211234. Я обычно сразу сохраняю такую карту полей в JSON-файл проекта, потому что руками эти идентификаторы не запоминаются, а при переносе интеграции на другой портал числа генерируются заново.

Фильтрация и постраничная выборка через crm.item.list

crm.item.list - рабочая лошадка для выгрузки данных: интеграций с BI, синхронизации с внешней базой, построения отчётов. Метод принимает entityTypeId, filter, select и order, работает как обычный REST-листинг Битрикс24 с постраничной выдачей по 50 записей за раз и параметром start для следующей страницы.

import requests

url = "https://your-domain.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/crm.item.list.json"
payload = {
    "entityTypeId": 1032,
    "filter": {
        "stageId": "DT1032_1:PAID",
        ">=dateCreate": "2026-07-01"
    },
    "select": ["id", "title", "stageId", "ufCrm_7_1667211234"],
    "order": {"dateCreate": "DESC"},
    "start": 0
}

response = requests.post(url, json=payload)
items = response.json().get("result", {}).get("items", [])

На практике фильтр по датам надёжнее собирать через >=dateCreate и 

Пакетные запросы и обновление статусов из внешних сервисов

Когда смарт-процесс завязан на внешние события, например статус оплаты через T‑Bank или статус доставки от СДЭК, точечные вызовы crm.item.update по одному элементу быстро упираются в лимит запросов Битрикс24, а это 2 запроса в секунду на веб-хук по умолчанию. Для пачки обновлений использую batch: один HTTP-запрос к методу batch с вложенными командами crm.item.update, до 50 команд за раз.

curl -X POST 
  "https://your-domain.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/batch.json" 
  -H "Content-Type: application/json" 
  -d '{
    "halt": 0,
    "cmd": {
      "upd1": "crm.item.update?entityTypeId=1032&id=451&fields[stageId]=DT1032_1:PAID",
      "upd2": "crm.item.update?entityTypeId=1032&id=452&fields[stageId]=DT1032_1:PAID"
    }
  }'

Из n8n такая связка собирается без единой строчки кода: HTTP-нода принимает вебхук платёжного шлюза, следующая нода мапит статус оплаты на stageId смарт-процесса, третья отправляет crm.item.update через HTTP Request node. Похожую схему я делал для интернет-магазина на Tilda: заказ создавался в смарт-процессе «Заказы», а оплата через T‑Bank переводила его в стадию «Оплачен» без участия менеджера. Если логики больше, чем пара условий, такие интеграции разумнее закладывать в проект на уровне бэкенда с обработкой ошибок и логированием, а не дособирать через десяток нод n8n на живую, для этого у меня есть услуга по интеграции CRM с внешними сервисами.

Частые ошибки при работе с crm.item

• Обращение к смарт-процессу через crm.deal.* или crm.lead.* вместо crm.item: метод либо вернёт ошибку о несуществующей сделке, либо просто не найдёт элемент.
• Использование в filter и select названия поля из интерфейса вместо кода ufCrm_N: Битрикс24 не сопоставляет их автоматически.
• Массовая синхронизация без batch-запросов: при превышении лимита метод отвечает 503 QUERY_LIMIT_EXCEEDED, и часть обновлений теряется, если не обрабатывать повтор.
• Попытка получить товарные позиции через crm.item.get: для строк товаров нужен отдельный метод crm.item.productrow.list, в основном ответе их нет.
• Копирование entityTypeId с тестового портала на боевой: при переносе интеграции ID смарт-процесса на новом аккаунте почти всегда другой, его нужно перепроверять через crm.type.list заново.

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

Чем entityTypeId отличается для разных смарт-процессов?

Это просто числовой идентификатор типа CRM-сущности, уникальный в рамках конкретного портала Битрикс24. Он присваивается автоматически при создании смарт-процесса и не переносится вместе с конфигурацией на другой аккаунт: на новом портале нужно заново получить его через crm.type.list и обновить в коде интеграции.

Можно ли использовать crm.item вместо crm.deal и crm.lead?

Технически методы crm.item покрывают и стандартные сущности CRM, у сделок и лидов тоже есть свои entityTypeId (1 и 2 соответственно). Но для них проще и стабильнее работать через привычные crm.deal.* и crm.lead.*, потому что там уже есть готовые системные поля и меньше риска столкнуться с расхождением версий API между старым и новым слоем методов.

Как получить список полей конкретного смарт-процесса?

Через метод crm.item.fields с параметром entityTypeId нужного процесса. В ответе будут системные поля и пользовательские с кодами вида ufCrm_N_идентификатор, вместе с типом каждого поля и списком допустимых значений для полей-списков.

Почему crm.item.list возвращает не все элементы?

Чаще всего причина в постраничной выдаче: по умолчанию метод отдаёт 50 записей, и без цикла с параметром start остальные просто не запрашиваются. Вторая частая причина - права доступа веб-хука или пользователя, от имени которого выполняется запрос: если у него нет доступа к части элементов смарт-процесса, они не попадут в выборку даже при точном фильтре.