crm.item.get в Битрикс24: читаем сделки и лиды

Работая с интеграциями Битрикс24, я долго дергал три-четыре разных метода, чтобы вытащить карточку сделки, лида и контакта: crm.deal.get, crm.lead.get, crm.contact.get, crm.company.get. У каждого свой набор полей, свои особенности формата. Метод crm.item.get решает эту проблему одним универсальным вызовом: указываешь тип сущности через entityTypeId и получаешь карточку в едином формате, независимо от того, сделка это, лид, контакт или смарт-процесс, который вы сами завели в CRM.

Что делает crm.item.get и зачем он появился в Битрикс24

До появления универсальных методов crm.item.* каждый тип CRM-сущности жил своей жизнью. У сделок был crm.deal.get с полями в формате TITLE, STAGE_ID, ASSIGNED_BY_ID. У лидов свой crm.lead.get с похожим, но не идентичным набором. Когда в портале появлялись смарт-процессы (SPA), те самые кастомные объекты вроде «Заявки на ремонт» или «Договоры», под них нельзя было использовать crm.deal.get, потому что это не сделка технически, хотя ведет себя как сделка в интерфейсе.crm.item.get закрывает эту дыру. Он читает данные любой сущности CRM: сделки, лида, контакта, компании и любого смарт-процесса, который вы создали через конструктор. Внутри метод обращается к той же базе, что и старые crm.deal.get и crm.lead.get, поэтому данные идентичны, разница только в оболочке запроса и в именах полей на выходе.Например, у одного клиента в CRM параллельно жили обычные сделки и смарт-процесс «Договоры на обслуживание». Синхронизация с внешней системой писалась один раз, а не дублировалась под каждый тип объекта отдельно, единственное, что менялось между вызовами, это значение entityTypeId.

Параметры entityTypeId и id: как собрать запрос

У crm.item.get три параметра, обязательных из них два:

• entityTypeId - числовой идентификатор типа сущности (сделка, лид, контакт, компания или ваш смарт-процесс);
• id - числовой идентификатор конкретной записи внутри этого типа;
• useOriginalUfNames - необязательный флаг формата имён пользовательских полей в ответе: Y отдаёт оригинальные имена вида UF_CRM_2_1639669411830, N отдаёт те же поля в camelCase, по умолчанию N.

Важный момент, на котором спотыкаются почти все, кто переходит со старых методов: у crm.item.get нет параметра select, как у crm.item.list. Метод всегда возвращает весь набор полей объекта целиком, отфильтровать их на уровне запроса нельзя, обрезать лишнее придется уже на своей стороне после получения ответа.Запрос отправляется методом POST (через входящий вебхук или REST-приложение), тело - обычный JSON или form-data с этими ключами. GET-запросы с параметрами в строке тоже принимаются входящими вебхуками Битрикс24, но для боевых интеграций я всегда использую POST, потому что так проще передавать вложенные структуры в других методах этого же семейства (add, update).

entityTypeId для сделок, лидов, контактов и своих объектов

Для стандартных сущностей CRM идентификаторы фиксированы и не меняются от портала к порталу, но четырьмя они не ограничены: в документации метода рядом с Лидом (1), Сделкой (2), Контактом (3) и Компанией (4) указан и Счёт (31), и другие системные типы. Ниже четыре, которые нужны чаще всего:

А вот со смарт-процессами так просто не будет. Их entityTypeId не фиксирован заранее, он выдается порталом в момент создания объекта через конструктор и обычно начинается со значений от 128 и выше. Узнать его можно методом crm.type.list, он возвращает список всех пользовательских типов CRM-объектов портала вместе с их entityTypeId. Я всегда сохраняю эти значения в конфиг интеграции сразу после того, как клиент завел новый смарт-процесс, потому что при пересоздании объекта id может измениться.

Чем ответ crm.item.get отличается от crm.deal.get

Главное отличие не в данных, а в именах полей. Старые методы отдают поля в верхнем регистре с подчеркиванием: TITLE, STAGE_ID, ASSIGNED_BY_ID, OPPORTUNITY, DATE_CREATE. Новый универсальный метод переходит на camelCase: title, stageId, assignedById, opportunity, createdTime.Это не косметика. Если у вас уже есть код, заточенный под старые поля, при переходе на crm.item.get его нужно переписывать, а не просто менять название метода в запросе, парсер ответа сломается на первом же обращении к несуществующему ключу TITLE вместо title.Ответ приходит в обертке result.item, а не result напрямую, как у некоторых старых методов. То есть значение достается так: result, затем item, затем title, а не result и сразу title.

Как устроены categoryId и stageId в ответе

У сделок и у смарт-процессов, где включены несколько воронок, стадия объекта не просто короткий код вроде PREPARATION. Идентификатор стадии учитывает воронку через поле categoryId: запись знает номер своей воронки, а stageId для не основной воронки идет с приставкой вида C5: перед кодом стадии, например C5:PREPARATION для пятой воронки. Если воронка основная и categoryId равен 0, приставка не добавляется, и stageId выглядит как обычный код без нее.Кусок типового ответа crm.item.get для сделки выглядит так:

{
  "result": {
    "item": {
      "id": 135,
      "title": "Заказ №135",
      "stageId": "C5:PREPARATION",
      "categoryId": 5,
      "opportunity": "45000.00",
      "contactId": 210,
      "companyId": 0,
      "assignedById": 12,
      "createdTime": "2026-08-01T10:15:00+03:00"
    }
  }
}

Примеры запроса: вебхук, PHP и JavaScript

Самый быстрый способ проверить метод - создать входящий вебхук в разделе разработчиков портала и дернуть его руками. Запрос на получение сделки с id 135 будет выглядеть так:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"entityTypeId": 2, "id": 135}' \
  https://your-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/crm.item.get

На PHP тот же запрос через curl выглядит так:

<?php
$url = 'https://your-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/crm.item.get';
$params = ['entityTypeId' => 2, 'id' => 135];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['result']['item']['title'];

На JavaScript, если запрос идет из серверной части или из виджета внутри приложения Битрикс24:

fetch('https://your-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/crm.item.get', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ entityTypeId: 3, id: 42 })
})
  .then(res => res.json())
  .then(data => console.log(data.result.item));

Такой запрос часто оказывается кирпичиком в более крупной цепочке: например, я собирал сценарий, где карточка сделки читается через crm.item.get, обогащается данными из внешнего сервиса и обратно пишется в Битрикс24 через crm.item.update. Если у клиента уже настроена автоматизацию бизнес-процессов в n8n, эти же запросы удобно завернуть в HTTP-ноду и не поднимать отдельный сервер под интеграцию.

Частые ошибки при чтении данных через crm.item.get

Забыли entityTypeId. Без него метод вернет ошибку валидации, потому что без указания типа сущности сервер не знает, в какой таблице искать id. Это не опечатка в документации, параметр обязателен всегда, даже если id встречается только у одного типа объектов на портале.Перепутали id смарт-процесса с id сделки. Идентификаторы записей внутри разных entityTypeId никак не связаны между собой: сделка с id 135 и смарт-процесс с id 135, это два разных объекта. Если в коде передать не тот entityTypeId, метод либо вернет ошибку «не найдено», либо, что хуже, тихо отдаст пустой результат, если у вебхука не хватает прав на этот тип сущности.Права вебхука настроены только на сделки. Входящий вебхук в Битрикс24 создается с конкретным набором разрешений по разделам (crm, lead, deal, contact и так далее). Если для смарт-процессов явно не выдали доступ, crm.item.get с чужим entityTypeId будет падать с ошибкой доступа, хотя сам метод существует и работает.Доступ закрыт на уровне воронки. Если у пользователя, от чьего имени работает REST-приложение, нет прав на конкретную воронку сделки, crm.item.get вернет ошибку доступа, даже если у пользователя вообще есть права на раздел сделок в целом, права CRM в Битрикс24 считаются и по разделу, и по конкретной воронке одновременно.Ожидание поля в старом формате. После переноса логики с crm.deal.get на crm.item.get части команды первое время присылают баг-репорты вида «пропало название сделки», а на деле это title вместо TITLE, просто другое имя ключа в том же самом ответе.

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

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

Можно ли через crm.item.get получить несколько записей за один запрос?

Нет, метод рассчитан на одну запись по конкретному id. Для выборки списка используется crm.item.list с фильтрами, сортировкой и параметром select, в отличие от get, там можно указать, какие поля нужны в ответе. На практике если нужно вытащить сразу пачку сделок для отчета или синхронизации, я использую crm.item.list с постраничной выборкой, а не дергаю crm.item.get по кругу для каждого id, так растет нагрузка на портал и метод быстрее упирается в лимиты запросов.

Работает ли crm.item.get со старыми crm.deal.get без переделки кода

Нет. Метод возвращает данные в другом формате: camelCase вместо TITLE_UPPERCASE, обертка result.item вместо прямого result. Код, читающий поля старого формата, придется адаптировать под новые имена ключей, простой заменой названия метода в запросе не обойтись.

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

Через метод crm.type.list, он возвращает список всех пользовательских типов CRM-объектов портала с их entityTypeId, названием и настройками. Заодно тем же вызовом можно получить и название объекта, которое видит пользователь в интерфейсе CRM, это удобно, если нужно показать читаемое имя типа сущности в логах интеграции.

Почему crm.item.get возвращает ошибку доступа, хотя сделка точно существует

Чаще всего дело в правах входящего вебхука или OAuth-приложения. Если при создании вебхука не выдали доступ к нужному разделу CRM (например, к смарт-процессам или к компаниям), метод будет отдавать ошибку доступа независимо от того, что сама запись в базе есть и видна в интерфейсе оператору.