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

Поля смарт-процессов

Создание, чтение, обновление и удаление пользовательских полей элементов смарт-процессов. Тип смарт-процесса задаётся в пути по идентификатору entityTypeId — публичному номеру из каталога смарт-процессов портала.

Битрикс24 API: userfieldconfig.* Скоуп: crm, userfieldconfig

Операции

Для встроенного смарт-счёта (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": "значение" }. Для других языков передавайте объект с кодами языков.

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

  1. Получить список смарт-процессов портала: GET /v1/smart-processes.
  2. Из ответа выбрать entityTypeId нужного типа.
  3. Посмотреть существующие поля смарт-процесса: GET /v1/items/:entityTypeId/userfields.
  4. Создать новое поле: POST /v1/items/:entityTypeId/userfields.
  5. Обновлять (PATCH) или удалять (DELETE) по id отдельной записи поля.

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