crm.deal.fields: как получить список полей сделки Битрикс24 и найти нужный UF-код

Метод crm.deal.fields битрикс24 REST API отдаёт полное описание всех полей сделки: стандартных и пользовательских, с типами, ограничениями и списком допустимых значений. Я обращаюсь к нему в первую очередь, когда настраиваю передачу данных в сделку из формы на Tilda, из aiogram-бота или из сценария n8n, и нужно понять, какой код поля подставлять в запрос вместо человекочитаемого названия из интерфейса CRM.

Зачем нужен crm.deal.fields и что он возвращает

Интерфейс сделки в Битрикс24 показывает подписи полей на русском: «Ответственный», «Источник», «Сумма», а REST API работает с внутренними кодами вроде ASSIGNED_BY_ID, SOURCE_ID, OPPORTUNITY. Для стандартных полей коды более-менее предсказуемы и описаны в документации, но как только в дело вступают пользовательские поля, добавленные администратором портала через интерфейс, угадать код не получится - он генерируется автоматически и выглядит как UF_CRM_1690000000123.

crm.deal.fields решает именно эту задачу: возвращает JSON, где по каждому полю указан код, тип, обязательность, доступность для записи и, если поле имеет фиксированный список значений, сами варианты с их внутренними ID. Без этого метода интеграция превращается в угадайку: отправляешь запрос crm.deal.add (в документации метод помечен DEPRECATED, замена crm.item.add с entityTypeId 2, старый пока доступен), получаешь ошибку валидации и по тексту ошибки пытаешься понять, что не так с полем, которое в интерфейсе называется «Способ доставки».

Отдельный нюанс - разница между crm.deal.fields и crm.deal.get. Первый метод описывает структуру: какие поля вообще существуют и что в них можно записать. Второй возвращает значения конкретной сделки по её ID. Начинающие разработчики иногда путают эти методы и пытаются вытащить список всех возможных полей из ответа crm.deal.get, но там будут только те поля, для которых в конкретной сделке заполнено значение, а не полная схема.

До того как я начал систематически прогонять crm.deal.fields перед каждой новой интеграцией, часть времени на проекте уходила на подбор кода поля методом проб и ошибок через crm.deal.add с разными вариантами и чтение текста ответа сервера. Один запрос к списку полей в начале работы экономит этот цикл целиком.

Как вызвать метод через REST API Битрикс24

Проще всего дёрнуть метод через входящий вебхук - для чтения списка полей достаточно прав на CRM, без обмена OAuth-токенами. В личном кабинете портала создаю вебхук в разделе «Разработчикам», получаю ссылку вида https://ваш-портал.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/ и подставляю в неё имя метода.

curl "https://ваш-портал.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/crm.deal.fields.json"

Тот же запрос из браузера или из фронтенда на JavaScript, если работаю с формой на Tilda и хочу сразу на клиенте свериться со списком полей перед отправкой:

fetch('https://ваш-портал.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/crm.deal.fields.json')
  .then(res => res.json())
  .then(data => console.log(data.result));

Если интеграция построена на серверной библиотеке CRest для PHP, вызов ещё короче:

$result = CRest::call('crm.deal.fields', []);
print_r($result['result']);

Вебхук подходит для большинства задач - чтения структуры полей, создания и обновления сделок от имени одного пользователя. Если нужна авторизация от лица разных сотрудников или работа с правами конкретного менеджера, тогда переходят на локальное приложение с OAuth, но сам вызов crm.deal.fields от этого не меняется, только способ получения токена.

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

Структура ответа: как читать описание каждого поля

Ответ - это объект, где ключи - коды полей, а значения - их метаданные. У каждого поля есть набор стандартных атрибутов.

Например, поле «Способ доставки», которое настроили под интеграцию с СДЭК, в ответе выглядит примерно так:

"UF_CRM_1690001234": {
  "type": "enumeration",
  "isRequired": false,
  "isReadOnly": false,
  "isMultiple": false,
  "isDynamic": true,
  "title": "Способ доставки",
  "listLabel": "Способ доставки",
  "items": [
    { "ID": "123", "VALUE": "СДЭК до двери" },
    { "ID": "124", "VALUE": "Самовывоз" }
  ]
}

Для поля со списком значений, например «Источник», в ответе будет не строка, а массив items, где у каждого варианта свой ID, именно его нужно передавать в crm.deal.add, а не текст, который видно в интерфейсе. Это частый источник ошибок: разработчик видит в интерфейсе значение «Реклама» и пытается отправить его как текст, вместо того чтобы взять числовой ID этого варианта из массива items.

Ещё один нюанс структуры ответа - атрибут statusType у полей типа crm_status: он показывает, к какому справочнику статусов привязано поле, например к воронке продаж или к источникам. Без этого атрибута можно перепутать, из какого именно справочника брать ID для конкретного поля, если в схеме сделки их несколько с похожими названиями.

Где искать UF-код нужного поля сделки

Стандартные поля и пользовательские UF_CRM_*

Стандартные поля сделки - TITLE, STAGE_ID, OPPORTUNITY, CURRENCY_ID, ASSIGNED_BY_ID, COMPANY_ID, CONTACT_ID - переходят из проекта в проект без изменений, их можно захардкодить. А вот пользовательские поля с префиксом UF_CRM_ уникальны для каждого портала: если клиент скопировал структуру CRM с одного аккаунта на другой или у вас несколько тестовых порталов, коды почти наверняка разойдутся даже при одинаковых названиях полей. Поэтому в коде интеграции я никогда не забиваю UF-код константой без проверки - в начале работы над проектом всегда прогоняю crm.deal.fields и фиксирую актуальные коды в конфиге.

Поиск по listLabel, а не по цвету кнопки в интерфейсе

Когда заказчик присылает скриншот карточки сделки и просит подставить в неё номер заказа с сайта, я открываю выгрузку crm.deal.fields, ищу по тексту нужную подпись в атрибутах title, listLabel или formLabel - обычно она совпадает с тем, что видно в интерфейсе, - и беру ключ объекта, в котором эта подпись встретилась. Быстрее всего это делать не глазами по JSON, а через Ctrl+F в текстовом редакторе или через фильтр в Postman: сохраняю ответ метода в файл и ищу по подстроке названия поля.

Кроме crm.deal.fields есть ещё crm.deal.userfield.list - он тоже возвращает пользовательские поля, но с дополнительными настройками: множественный выбор, значения по умолчанию, привязку к справочнику. Для быстрого поиска кода поля достаточно первого метода, а userfield.list пригождается, когда нужно создать новое поле программно или разобраться с настройками существующего справочника.

Практика: получаю поля сделки в n8n, PHP и Telegram-боте

В n8n перед тем как строить сценарий «заявка с сайта - сделка в Битрикс24», я добавляю отдельный HTTP Request node на crm.deal.fields, смотрю результат в панели вывода и потом уже в основном node с crm.deal.add прописываю JSON body с реальными кодами полей. Так исключается ситуация, когда автоматизация отваливается через день с ошибкой валидации, которую сложно поймать без логов.

Похожая история с интеграцией доставки СДЭК: если в сделке нужно хранить код пункта выдачи, для него на портале обычно заведено кастомное поле вида UF_CRM_1690001234, и без предварительного запроса crm.deal.fields угадать этот код нереально, только перебором через API или через выгрузку в интерфейсе администратора, которая тоже требует прав разработчика.

В aiogram-боте, который создаёт сделку прямо из диалога в Telegram, я обычно кэширую результат crm.deal.fields на старте приложения - раз в сутки или при деплое, - чтобы не дёргать метод на каждое сообщение пользователя, а маппинг «шаг диалога - код поля» держу в отдельном словаре рядом с логикой сценария.

Для заявок с сайта на Tilda я обычно свожу коды полей в простую таблицу соответствия: название поля формы слева, код из crm.deal.fields справа. Такую таблицу легко передать другому разработчику или подрядчику, который продолжит проект, и она же служит документацией на случай, если через полгода понадобится добавить ещё одно поле в ту же интеграцию.

Когда типового вебхука не хватает и нужна доработка на стороне сервера: валидация значений enumeration перед отправкой, синхронизация UF-полей с внешней базой или миграция структуры CRM между порталами, такие задачи я беру как автоматизацию процессов и интеграций под конкретный процесс заказчика, а не как разовый скрипт.

После того как коды полей собраны и интеграция настроена, я обычно ещё раз прогоняю crm.deal.fields перед сдачей проекта - за время разработки администратор портала мог добавить новое обязательное поле или изменить список значений в справочнике, и лучше поймать это до релиза, а не после первой сделки, созданной клиентом через сайт.

Частые ошибки при работе с полями сделки

• Передавать в enumeration-поле текст из интерфейса вместо ID варианта из items - метод либо примет запрос с неверным значением, либо вернёт ошибку валидации в зависимости от поля.
• Для isMultiple-полей отправлять одно значение строкой вместо массива - Битрикс24 либо отклонит запрос, либо запишет только часть значения.
• Хардкодить UF-код, скопированный с тестового портала, в продакшен-интеграцию - на боевом аккаунте у того же по смыслу поля почти всегда другой числовой суффикс.
• Вызывать метод без прав на CRM в scope вебхука - тогда вернётся ошибка авторизации ещё до того, как появится список полей.
• Забывать, что обязательность поля может зависеть от направления сделки, то есть от воронки: crm.deal.fields отдаёт общую схему, а не то, какие поля требуются именно на конкретной стадии конкретной воронки - это уже логика crm.dealcategory и настроек стадии.

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

Чем crm.deal.fields отличается от crm.deal.userfield.list?

crm.deal.fields отдаёт полный список полей сделки, включая стандартные, в едином формате - удобно для быстрого поиска кода перед отправкой запроса. crm.deal.userfield.list работает только с пользовательскими полями и возвращает больше настроек: значения по умолчанию, привязку к справочнику, параметры отображения. Для рядовой задачи найти UF-код хватает первого метода.

Как узнать код поля, которое видно только в интерфейсе сделки?

Выгружаю результат crm.deal.fields целиком в файл и ищу по тексту подпись, которая видна в карточке сделки - она обычно совпадает с атрибутом title или listLabel нужного поля. Если совпадений несколько, дополнительно сверяюсь по типу поля и по разделу интерфейса, в котором оно показано.

Почему UF-код одного и того же поля разный на двух порталах?

Числовой суффикс в UF_CRM_ Битрикс24 генерирует автоматически при создании поля, он завязан на внутренний идентификатор записи в базе портала. Даже если название поля и его настройки полностью совпадают, при переносе структуры CRM на другой аккаунт код почти всегда получится другим, поэтому его нельзя переносить между проектами без повторного запроса метода.

Нужны ли особые права доступа для вызова crm.deal.fields?

Достаточно вебхука с доступом к разделу CRM - того же, что обычно выдают для чтения и создания сделок. Отдельных прав именно на схему полей Битрикс24 не выделяет: если вебхук может работать со сделками, он может и прочитать их структуру.