ID поля — он же код или символьный идентификатор — это имя, по которому Битрикс24 узнаёт поле в роботах, бизнес-процессах, REST API и вебхуках. Системные поля имеют фиксированные читаемые коды — TITLE, OPPORTUNITY; пользовательские получают код вида UF_CRM_ с числом. В статье разберём, где посмотреть код поля, почему одно и то же поле пишется по-разному в разных API и как использовать коды в автоматизации.

Что такое ID поля и чем он отличается от названия?

У каждого поля два имени. Название — «Сумма», «Источник» — видят пользователи; его можно менять в любой момент, на работу системы это не влияет. Код — OPPORTUNITY, SOURCE_ID — служебный идентификатор: по нему поле находят роботы, бизнес-процессы, API-запросы и шаблоны документов. Код фиксируется при создании поля и дальше не меняется. Отсюда практическое правило: в автоматизации опирайтесь на код, а не на название. Переименование поля сломает всё, что завязано на текст названия, и не тронет того, что завязано на код, — поэтому интеграции и процессы, собранные на кодах, переживают любые косметические правки карточки.

Как узнать ID поля в настройках CRM?

Самый короткий путь — настройки полей: откройте CRM → Настройки, выберите сущность и нужное поле — код отображается в карточке поля. Системные коды осмысленны: TITLE — название, OPPORTUNITY — сумма, ASSIGNED_BY_ID — ответственный, COMMENTS — комментарий. Пользовательские поля получают автоматический код вида UF_CRM_ плюс длинное число — задать его вручную при создании через интерфейс нельзя, поэтому «нечитаемый» код — это нормально. В задачах пользовательские поля имеют префикс UF_, в смарт-процессах коды строятся по тому же принципу. Если поле создавали давно и никто не помнит зачем, код помогает найти все места, где оно используется, — от бизнес-процессов до вебхуков.

Как получить полный список полей через API?

Когда полей десятки, удобнее запросить весь список разом: REST-методы вида crm.deal.fields и crm.contact.fields (или универсальный crm.item.fields) возвращают JSON со всеми полями сущности — код, тип и название каждого. Достаточно входящего вебхука с правами на CRM: вставьте URL метода в браузер и получите полный справочник полей вашего портала. Этот же приём решает обратную задачу — по названию найти код, когда настроек CRM под рукой нет. Список полей пригодится и при подстановке значений в переменные бизнес-процесса: прежде чем строить процесс, полезно выписать коды всех полей, которые он читает и пишет.

Почему TITLE и title — это одно поле?

В Битрикс24 два поколения REST API, и коды в них пишутся по-разному. Старые методы (crm.deal.update) и дизайнер бизнес-процессов используют верхний регистр: TITLE, OPPORTUNITY, UF_CRM_…. Универсальный API crm.item.* использует camelCase: title, opportunity, assignedById. Это одно и то же поле в двух написаниях, и путаница между ними — частая причина ситуации «робот отработал, а значение не записалось». Правило: формат кода смотрите в документации конкретного метода или в подсказке робота. Например, робот «Обновить сделку по ID» работает через универсальный API и принимает JSON в camelCase: {"title":"Новая сделка","stageId":"C1:WON","opportunity":50000}.

Как использовать ID полей в роботах?

Три типовые операции. Прочитать значение по коду — робот «Получить значение поля связанной сущности»: тип сущности, её ID и код поля (TITLE, ASSIGNED_BY_ID или UF_CRM_…) — на выходе значение и признак «найдено» Y/N. Записать несколько полей разом — «Обновить сделку по ID»: ID сделки и JSON, где ключи — те самые коды полей. Разобрать ответ внешней системы — «Извлечь значение из JSON по пути»: достаёт значение по пути через точку (например, data.user.email) из JSON, который вернул вебхук или внешний сервис, и возвращает его строкой плюс признак «путь найден» Y/N. Во всех трёх случаях коды полей — общий язык между CRM, процессом и внешними системами.

Итог

Код поля — постоянный служебный идентификатор: системные коды читаемы (TITLE, OPPORTUNITY), пользовательские генерируются с префиксом UF_CRM_. Смотрите коды в настройках полей CRM или через методы *.fields и опирайтесь в автоматизации только на них. Роботы для чтения и записи полей по кодам — в каталоге Роботеки; нет нужного — опишите задачу, сделаем робота бесплатно.