## Создать поле `POST /v1/items/:entityTypeId/userfields` Создаёт новое пользовательское поле для элементов смарт-процесса. Возвращает HTTP `201 Created` с `id` нового поля. Поля передаются плоско в корне JSON — без обёртки `fields`. ## Параметры | Параметр | Тип | Обяз. | Описание | |----------|-----|:-----:|---------| | `:entityTypeId` (path) | number | да | Идентификатор типа смарт-процесса. Источник: [`GET /v1/smart-processes`](/docs/entities/smart-processes) — поле `entityTypeId` в каждом элементе массива `data` | ## Поля запроса (body) | Поле | Тип | Обяз. | Описание | |------|-----|:-----:|---------| | `userTypeId` | string | да | Тип поля. Список допустимых значений — [`GET /v1/items/:entityTypeId/userfields/types`](/docs/userfields/smart-processes/types). Примеры: `string`, `enumeration`, `integer`, `double`, `datetime` | | `fieldName` | string | да | Полное системное имя в формате `UF_CRM__<суффикс>`. Здесь `typeId` — это поле `id` (внутренний ID типа) из ответа [`GET /v1/smart-processes`](/docs/entities/smart-processes/list), а не `entityTypeId` из пути запроса: значения различаются. Поле `id` доступно всегда, даже если у смарт-процесса ещё нет полей. Авто-генерация не поддерживается: бэкенд не достраивает префикс, неполное имя даёт `422 BITRIX_ERROR` | | `label` | string | нет | Подпись поля для отображения. Если не заданы явные `editFormLabel` / `listColumnLabel`, значение копируется в обе подписи — формы редактирования (`editFormLabel`) и заголовка столбца списка (`listColumnLabel`). Для подписей по конкретным языкам используйте объекты `editFormLabel` / `listColumnLabel` | | `editFormLabel` | object | нет | Подпись в форме редактирования по языкам. Пример: `{ "ru": "Проект", "en": "Project" }`. Значения устанавливаются для указанных языков. Остальные локали заполняются по правилам Битрикс24 | | `sort` | string | нет | Порядок сортировки в интерфейсе Битрикс24. По умолчанию `"100"` | | `multiple` | string | нет | Разрешить несколько значений: `"Y"` или `"N"`. По умолчанию `"N"` | | `mandatory` | string | нет | Обязательное при заполнении: `"Y"` или `"N"`. По умолчанию `"N"` | | `showFilter` | string | нет | Отображать в фильтре: `"N"` — нет, `"I"` — точное значение, `"E"` — маска, `"S"` — диапазон | | `showInList` | string | нет | Показывать в списке записей: `"Y"` или `"N"` | | `editInList` | string | нет | Разрешить редактирование прямо из списка: `"Y"` или `"N"` | | `isSearchable` | string | нет | Участвует в полнотекстовом поиске: `"Y"` или `"N"` | | `xmlId` | string | нет | Внешний идентификатор для интеграций | | `settings` | object | нет | Настройки поля, специфичные для `userTypeId`. Для `string` — `SIZE`, `ROWS`, `REGEXP`, `MIN_LENGTH`, `MAX_LENGTH`, `DEFAULT_VALUE`. Состав зависит от типа | | `enum` | array | нет | Варианты для поля типа `enumeration`. Каждый элемент: `{ "value": "Название", "sort": 10 }` (опционально `"def": "Y"` — значение по умолчанию). Тот же массив принимается и под ключом `list` — формат элемента одинаковый. При чтении поля варианты возвращаются в блоке `enum` | ## Примеры ### curl — личный ключ ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/items/174/userfields" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "userTypeId": "enumeration", "fieldName": "UF_CRM_3_PROJECT_STATUS", "label": "Статус проекта", "sort": "200", "showFilter": "I", "showInList": "Y", "enum": [ { "value": "Новый", "sort": 10 }, { "value": "В работе", "sort": 20 }, { "value": "Завершён", "sort": 30 } ] }' ``` ### curl — OAuth-приложение ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/items/174/userfields" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "userTypeId": "enumeration", "fieldName": "UF_CRM_3_PROJECT_STATUS", "label": "Статус проекта", "sort": "200", "showFilter": "I", "showInList": "Y", "enum": [ { "value": "Новый", "sort": 10 }, { "value": "В работе", "sort": 20 }, { "value": "Завершён", "sort": 30 } ] }' ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/items/174/userfields', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ userTypeId: 'enumeration', fieldName: 'UF_CRM_3_PROJECT_STATUS', label: 'Статус проекта', sort: '200', showFilter: 'I', showInList: 'Y', enum: [ { value: 'Новый', sort: 10 }, { value: 'В работе', sort: 20 }, { value: 'Завершён', sort: 30 }, ], }), }) const { success, data } = await res.json() console.log('Создано поле с id:', data.id) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/items/174/userfields', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ userTypeId: 'enumeration', fieldName: 'UF_CRM_3_PROJECT_STATUS', label: 'Статус проекта', sort: '200', showFilter: 'I', showInList: 'Y', enum: [ { value: 'Новый', sort: 10 }, { value: 'В работе', sort: 20 }, { value: 'Завершён', sort: 30 }, ], }), }) const { success, data } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | Всегда `true` при успехе | | `data.id` | string | Идентификатор созданного поля. Возвращается строкой. При чтении через [Получить поле](/docs/userfields/smart-processes/get) то же значение приходит числом | ## Пример ответа ```json { "success": true, "data": { "id": "7119" } } ``` ## Пример ответа при ошибке 422 — некорректное имя поля (не в формате `UF_CRM__<суффикс>`): ```json { "success": false, "error": { "code": "BITRIX_ERROR", "message": "Некорректный код поля" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `MISSING_FIELD` | Не передан обязательный параметр `userTypeId` | | 400 | `INVALID_REQUEST` | Тело запроса не является объектом | | 400 | `INVALID_ENTITY_TYPE_ID` | `:entityTypeId` не является положительным целым числом | | 403 | `BITRIX_ACCESS_DENIED` | У ключа нет скоупа `userfieldconfig` — перевыпустите ключ с этим скоупом | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `crm` | | 404 | `SMART_PROCESS_NOT_FOUND` | Смарт-процесс с указанным `entityTypeId` не найден на портале | | 422 | `BITRIX_ERROR` | Некорректный код поля — `fieldName` не в формате `UF_CRM__<суффикс>` | | 422 | `BITRIX_ERROR` | Неизвестный `userTypeId` (не из каталога [`/types`](/docs/userfields/smart-processes/types)), дублирующее имя поля или некорректные `settings` | | 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов | | 401 | `MISSING_API_KEY` | Отсутствует заголовок `X-Api-Key` | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Смотрите также - [Каталог типов полей](/docs/userfields/smart-processes/types) - [Получить поле](/docs/userfields/smart-processes/get) - [Обновить поле](/docs/userfields/smart-processes/update) - [Удалить поле](/docs/userfields/smart-processes/delete) - [Поля смарт-процессов](/docs/userfields/smart-processes) - [Пользовательские поля](/docs/userfields)