REST: пользовательские поля CRM

Пользовательские поля расширяют стандартные карточки CRM своими данными. Через семейство crm.*.userfield.* внешняя система может создавать поля, читать их конфигурацию и наполнять значениями наравне со штатными полями.

Что такое пользовательские поля

Пользовательское поле (userfield) — это дополнительный атрибут сущности CRM: сделки, лида, контакта, компании или смарт-процесса. В API оно всегда имеет код с префиксом UF_CRM_, например UF_CRM_1690000000.

Управление полями разнесено по сущностям:

• crm.deal.userfield.* — поля сделок;
• crm.lead.userfield.* — поля лидов;
• crm.contact.userfield.* / crm.company.userfield.* — контакты и компании.

Создание поля: userfield.add

Метод crm.deal.userfield.add заводит новое поле. Обязательны тип и код (без префикса — он добавится сам):

{ "fields": { "FIELD_NAME": "DELIVERY_DATE", "USER_TYPE_ID": "date", "XML_ID": "delivery_date", "EDIT_FORM_LABEL": { "ru": "Дата доставки" }, "LIST_COLUMN_LABEL": { "ru": "Доставка" }, "MANDATORY": "N", "MULTIPLE": "N" } }

Итоговый код поля станет UF_CRM_DELIVERY_DATE. Если FIELD_NAME не задать явно, Битрикс24 сгенерирует числовой код.

Метки EDIT_FORM_LABEL и LIST_COLUMN_LABEL задаются объектом с языковыми ключами — это подписи в карточке и в списке. Флаги MANDATORY (обязательное) и MULTIPLE (множественное) определяют поведение поля. Множественное поле хранит массив значений и в выборке возвращается массивом, что нужно учитывать при разборе ответа.

Типы пользовательских полей

Тип задаётся в USER_TYPE_ID. Основные типы:

Тип определяет не только валидацию, но и формат передачи значения. Поле date ждёт дату в ISO-формате, boolean — 1/0, crm — идентификатор с префиксом сущности (например D_1024 для сделки), file — контент в base64. Ошибочный формат приводит к тихому пропуску значения без явной ошибки, поэтому тип поля важно сверять с *.userfield.get.

Списочные поля (enumeration)

Для поля-списка значения задаются прямо при создании через параметр LIST:

{ "fields": { "FIELD_NAME": "PRIORITY", "USER_TYPE_ID": "enumeration", "LIST": [ { "VALUE": "Высокий" }, { "VALUE": "Средний", "DEF": "Y" }, { "VALUE": "Низкий" } ] } }

Изменение вариантов списка выполняется через *.userfield.update с массивом LIST: чтобы удалить пункт, передайте его ID и DEL: "Y".

Использование в add, update и фильтрах

После создания поле работает как штатное. Записать значение при создании сделки:

crm.deal.add с телом { "fields": { "TITLE": "Заказ", "UF_CRM_DELIVERY_DATE": "2026-08-01" } }.

• чтобы получить пользовательские поля в выборке, добавьте их коды (или *) в select;
• фильтровать можно по коду поля: { "filter": { "UF_CRM_PRIORITY": 42 } };
• множественные поля возвращаются массивом значений.

Одни и те же поля доступны и в crm.deal.add, и в crm.deal.update, и в фильтрах list, поэтому единожды заведённое поле сразу становится частью полноценного API сущности. Для поля типа crm в фильтре передавайте идентификатор с префиксом, а для множественного — массив значений. Это делает пользовательские поля равноправным инструментом интеграции, а не просто визуальным дополнением карточки.

Просмотр, изменение и удаление

Управление конфигурацией полей:

• crm.deal.userfield.list — все поля сущности с фильтром и сортировкой;
• crm.deal.userfield.get — одно поле по ID (включая варианты списка);
• crm.deal.userfield.update — правка меток, обязательности, вариантов;
• crm.deal.userfield.delete — удаление поля вместе со всеми значениями.

Обратите внимание, что userfield.update принимает внутренний числовой ID поля, а не его текстовый код UF_CRM_*. Поэтому перед изменением конфигурации получите поле через list или get и возьмите оттуда ID. Список полей удобно кешировать на старте интеграции: он меняется редко, а обращения к нему при каждой операции создают лишнюю нагрузку и расход лимитов.

Итог

Пользовательские поля через crm.*.userfield.* позволяют расширять CRM под свои процессы: даты, суммы, списки, привязки. Ключевые нюансы — префикс UF_CRM_, хранение ID у списочных полей и обязательное добавление кодов в select при выборке.

Мы в B2Bsite проектируем структуру полей CRM под реальные данные бизнеса и настраиваем их наполнение из сайта, форм и 1С через REST. Если карточкам сделок и контактов не хватает нужных атрибутов — поможем спроектировать и заполнить их автоматически.