Для AI-агентов: markdown этой страницы — /docs-content/userfields/crm.md индекс документации — /llms.txt
Поля CRM-сущностей
Создание, чтение, обновление и удаление пользовательских полей для фиксированных CRM-сущностей: сделок, лидов, контактов, компаний, предложений и реквизитов. Сущность задаётся в пути запроса (:entity).
Битрикс24 API: crm.<entity>.userfield.*
Скоуп: crm
Операции
- Список полей сущности —
GET /v1/userfields/:entity - Каталог типов —
GET /v1/userfields/:entity/types - Получить поле —
GET /v1/userfields/:entity/:id - Создать поле —
POST /v1/userfields/:entity - Обновить поле —
PATCH /v1/userfields/:entity/:id - Удалить поле —
DELETE /v1/userfields/:entity/:id
Поддерживаемые сущности
: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"
при записи выключают фильтр.
Типовой сценарий
- Посмотреть список уже созданных полей:
GET /v1/userfields/deals. - Уточнить доступные типы:
GET /v1/userfields/deals/types. - Создать новое поле с обязательным
userTypeId:POST /v1/userfields/deals. - Прочитать его полное описание со значениями списка (для
enumeration):GET /v1/userfields/deals/:id. При создании и обновлении сделки такое поле принимаетIDварианта изdata.list, а не подписьVALUE. Подпись вместоIDтеряется без ошибки. Подробнее — Формат значения по типам. - Обновить (
PATCH) или удалить (DELETE) по идентификатору.