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

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

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

## Операции

- [Список полей](/docs/userfields/smart-processes/list) — `GET /v1/items/:entityTypeId/userfields`
- [Каталог типов](/docs/userfields/smart-processes/types) — `GET /v1/items/:entityTypeId/userfields/types`
- [Получить поле](/docs/userfields/smart-processes/get) — `GET /v1/items/:entityTypeId/userfields/:id`
- [Создать поле](/docs/userfields/smart-processes/create) — `POST /v1/items/:entityTypeId/userfields`
- [Обновить поле](/docs/userfields/smart-processes/update) — `PATCH /v1/items/:entityTypeId/userfields/:id`
- [Удалить поле](/docs/userfields/smart-processes/delete) — `DELETE /v1/items/:entityTypeId/userfields/:id`

Для встроенного смарт-счёта (`entityTypeId=31`) те же шесть операций доступны и по пути
`/v1/userfields/invoices` — с теми же суффиксами и телом запроса.

## Получение `entityTypeId`

Идентификатор типа смарт-процесса возвращается в ответе [`GET /v1/smart-processes`](/docs/entities/smart-processes) — поле `entityTypeId` в каждом элементе массива `data`. Для встроенных CRM-сущностей (сделки, лиды, контакты, компании, предложения, реквизиты) используйте раздел [Поля CRM-сущностей](/docs/userfields/crm) — он работает с фиксированным набором сущностей через `:entity`-имя.

В ответах userfield-эндпоинтов обычных смарт-процессов поле `entityId` приходит в формате
`CRM_<typeId>`, где `typeId` — внутренний последовательный идентификатор смарт-процесса.
Это не совпадает с публичным `entityTypeId` из пути запроса. Для встроенного смарт-счёта
`entityTypeId=31` используется специальный `entityId=CRM_SMART_INVOICE`. Имена полей в ответах
возвращаются в формате Битрикс24 `UF_CRM_<typeId>_*`. В схеме элемента и в запросах к элементам то же
поле называется `ufCrm<typeId>_*` — например `UF_CRM_3_1628508847` и `ufCrm3_1628508847`. Рабочее имя
для чтения и записи значений берётся из `GET /v1/items/{entityTypeId}/fields`, форматы значений по
типам — [Пользовательские поля (UF)](/docs/entity-api#пользовательские-поля-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) |
|-----------------|------------------------|
| `id` | `ID` |
| `entityId` | `ENTITY_ID` |
| `fieldName` | `FIELD_NAME` |
| `userTypeId` | `USER_TYPE_ID` |
| `xmlId` | `XML_ID` |
| `sort` | `SORT` |
| `multiple` | `MULTIPLE` |
| `mandatory` | `MANDATORY` |
| `showFilter` | `SHOW_FILTER` |
| `showInList` | `SHOW_IN_LIST` |
| `editInList` | `EDIT_IN_LIST` |
| `isSearchable` | `IS_SEARCHABLE` |
| `label` | `LABEL` |
| `editFormLabel` | `EDIT_FORM_LABEL` |
| `listColumnLabel` | `LIST_COLUMN_LABEL` |
| `listFilterLabel` | `LIST_FILTER_LABEL` |
| `errorMessage` | `ERROR_MESSAGE` |
| `helpMessage` | `HELP_MESSAGE` |
| `settings` | `SETTINGS` |
| `enum` | варианты поля `enumeration` (см. [Получить поле](/docs/userfields/smart-processes/get)) |

Если при создании или обновлении передать `label` без явных `editFormLabel` / `listColumnLabel`, значение копируется в обе подписи — формы редактирования (`editFormLabel`) и заголовка столбца списка (`listColumnLabel`).

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

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

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

- [Поля CRM-сущностей](/docs/userfields/crm)
- [Смарт-процессы](/docs/entities/smart-processes)
- [Пользовательские поля](/docs/userfields)