Для AI-агентов: markdown этой страницы — /docs-content/userfields/smart-processes.md индекс документации — /llms.txt
Поля смарт-процессов
Создание, чтение, обновление и удаление пользовательских полей элементов смарт-процессов. Тип смарт-процесса задаётся в пути по идентификатору entityTypeId — публичному номеру из каталога смарт-процессов портала.
Битрикс24 API: userfieldconfig.*
Скоуп: crm, userfieldconfig
Операции
- Список полей смарт-процесса —
GET /v1/items/:entityTypeId/userfields - Каталог типов —
GET /v1/items/:entityTypeId/userfields/types - Получить поле —
GET /v1/items/:entityTypeId/userfields/:id - Создать поле —
POST /v1/items/:entityTypeId/userfields - Обновить поле —
PATCH /v1/items/:entityTypeId/userfields/:id - Удалить поле —
DELETE /v1/items/:entityTypeId/userfields/:id
Для встроенного смарт-счёта (entityTypeId=31) те же шесть операций доступны и по пути
/v1/userfields/invoices — с теми же суффиксами и телом запроса.
Получение `entityTypeId`
Идентификатор типа смарт-процесса возвращается в ответе GET /v1/smart-processes — поле entityTypeId в каждом элементе массива data. Для встроенных CRM-сущностей (сделки, лиды, контакты, компании, предложения, реквизиты) используйте раздел Поля CRM-сущностей — он работает с фиксированным набором сущностей через :entity-имя.
В ответах userfield-эндпоинтов обычных смарт-процессов поле entityId приходит в формате
CRM_<typeId>, где typeId — внутренний последовательный идентификатор смарт-процесса.
Это не совпадает с публичным entityTypeId из пути запроса. Для встроенного смарт-счёта
entityTypeId=31 используется специальный entityId=CRM_SMART_INVOICE. Имена полей в ответах
возвращаются в формате Битрикс24 UF_ + entityId + _*: UF_CRM_<typeId>_* у обычного смарт-процесса,
UF_CRM_SMART_INVOICE_* у смарт-счёта. Тот же префикс обязателен в fieldName при создании поля. В схеме элемента и в запросах к элементам то же
поле называется ufCrm<typeId>_* — например UF_CRM_3_1628508847 и ufCrm3_1628508847. Рабочее имя
для чтения и записи значений берётся из GET /v1/items/{entityTypeId}/fields, форматы значений по
типам — Пользовательские поля (UF).
Требования к скоупам ключа
Чтение и запись полей смарт-процессов требуют двух скоупов у API-ключа:
crm— общий скоуп раздела для всех/v1/items/*и/v1/userfields/*.userfieldconfig— отдельный скоуп управления полями смарт-процессов. Опциональный — отметьте его в списке прав при создании ключа.
Без скоупа userfieldconfig любой запрос (кроме /types, для которого достаточно crm) возвращает 403 BITRIX_ACCESS_DENIED. Скоуп фиксируется в момент выпуска ключа: если добавить право уже существующему ключу, нужно перевыпустить его — иначе скоуп не применится. Эндпоинт /types использует только crm.
Соответствие имён полей
В теле запроса и в ответе используются camelCase-имена. Вложенные структуры (settings, элементы массива enum) Битрикс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)enum |
Битрикс24 (UPPER_CASE)варианты поля enumeration (см. Получить поле) |
При создании или обновлении label заполняет каждую из трёх подписей, если она не передана явно: подпись формы редактирования (editFormLabel), заголовок столбца списка (listColumnLabel) и подпись фильтра (listFilterLabel). Явно переданные подписи сохраняются независимо друг от друга. Строковая подпись преобразуется в объект { "ru": "значение" }. Для других языков передавайте объект с кодами языков.
Типовой сценарий
- Получить список смарт-процессов портала:
GET /v1/smart-processes. - Из ответа выбрать
entityTypeIdнужного типа. - Посмотреть существующие поля смарт-процесса:
GET /v1/items/:entityTypeId/userfields. - Создать новое поле:
POST /v1/items/:entityTypeId/userfields. - Обновлять (
PATCH) или удалять (DELETE) поidотдельной записи поля.