Для AI-агентов: markdown этой страницы — /docs-content/userfields/crm.md индекс документации — /llms.txt

Поля CRM-сущностей

Создание, чтение, обновление и удаление пользовательских полей для фиксированных CRM-сущностей: сделок, лидов, контактов, компаний, предложений и реквизитов. Сущность задаётся в пути запроса (:entity).

Битрикс24 API: crm.<entity>.userfield.* Скоуп: crm

Операции

Поддерживаемые сущности

:entity в пути — одно из значений ниже. В ответе поле entityId содержит соответствующий внутренний идентификатор Битрикс24.

:entity entityId в ответе Сущность
:entitydeals entityId в ответеCRM_DEAL СущностьСделка
:entityleads entityId в ответеCRM_LEAD СущностьЛид
:entitycontacts entityId в ответеCRM_CONTACT СущностьКонтакт
:entitycompanies entityId в ответеCRM_COMPANY СущностьКомпания
:entityquotes entityId в ответеCRM_QUOTE СущностьПредложение
:entityrequisites entityId в ответеCRM_REQUISITE СущностьРеквизиты

Соответствие имён полей

Таблица описывает свойства самого поля: в теле запроса и в ответе они называются camelCase-именами, а Битрикс24 хранит их в UPPER_CASE. Это помогает читать вложенные структуры (settings, элементы массива list), которые Битрикс24 возвращает «как есть». Имя поля в запросах к записям сущности — Значения полей в записях.

API (camelCase) Битрикс24 (UPPER_CASE)
API (camelCase)id Битрикс24 (UPPER_CASE)ID
API (camelCase)entityId Битрикс24 (UPPER_CASE)ENTITY_ID
API (camelCase)fieldName Битрикс24 (UPPER_CASE)FIELD_NAME
API (camelCase)userTypeId Битрикс24 (UPPER_CASE)USER_TYPE_ID
API (camelCase)xmlId Битрикс24 (UPPER_CASE)XML_ID
API (camelCase)sort Битрикс24 (UPPER_CASE)SORT
API (camelCase)multiple Битрикс24 (UPPER_CASE)MULTIPLE
API (camelCase)mandatory Битрикс24 (UPPER_CASE)MANDATORY
API (camelCase)showFilter Битрикс24 (UPPER_CASE)SHOW_FILTER
API (camelCase)showInList Битрикс24 (UPPER_CASE)SHOW_IN_LIST
API (camelCase)editInList Битрикс24 (UPPER_CASE)EDIT_IN_LIST
API (camelCase)isSearchable Битрикс24 (UPPER_CASE)IS_SEARCHABLE
API (camelCase)label Битрикс24 (UPPER_CASE)LABEL
API (camelCase)editFormLabel Битрикс24 (UPPER_CASE)EDIT_FORM_LABEL
API (camelCase)listColumnLabel Битрикс24 (UPPER_CASE)LIST_COLUMN_LABEL
API (camelCase)listFilterLabel Битрикс24 (UPPER_CASE)LIST_FILTER_LABEL
API (camelCase)errorMessage Битрикс24 (UPPER_CASE)ERROR_MESSAGE
API (camelCase)helpMessage Битрикс24 (UPPER_CASE)HELP_MESSAGE
API (camelCase)settings Битрикс24 (UPPER_CASE)SETTINGS
API (camelCase)list Битрикс24 (UPPER_CASE)LIST

Флаги «да/нет»

Шесть свойств из таблицы — multiple, mandatory, showFilter, showInList, editInList, isSearchable — Битрикс24 хранит не булевыми, а символьными флагами. Присылайте их булевыми (true / false) либо строками "Y" / "N" — платформа приводит обе формы. Пять из шести хранятся как "Y" и "N"; у showFilter форма хранения своя — см. ниже.

Отдельно про showFilter. Включают его обычным true или "Y", а при ЧТЕНИИ включённый фильтр возвращается как "E" — это форма хранения Битрикс24. Прочитанное "E" можно отправить обратно как есть: платформа понимает его как «включён», поэтому цикл «прочитал → поменял одно поле → отправил целиком» фильтр не гасит. Это верно, когда прочитано "N" или "E"; поле, настроенное вне этого метода, может нести иное значение — такое обратно не отправляйте, включайте true. Буквы "I" и "S" при записи выключают фильтр.

Типовой сценарий

  1. Посмотреть список уже созданных полей: GET /v1/userfields/deals.
  2. Уточнить доступные типы: GET /v1/userfields/deals/types.
  3. Создать новое поле с обязательным userTypeId: POST /v1/userfields/deals.
  4. Прочитать его полное описание со значениями списка (для enumeration): GET /v1/userfields/deals/:id. При создании и обновлении сделки такое поле принимает ID варианта из data.list, а не подпись VALUE. Подпись вместо ID теряется без ошибки. Подробнее — Формат значения по типам.
  5. Обновить (PATCH) или удалить (DELETE) по идентификатору.

Смотрите также