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

Создать поле

POST /v1/items/:entityTypeId/userfields

Создаёт новое пользовательское поле для элементов смарт-процесса. Возвращает HTTP 201 Created с id нового поля. Поля передаются плоско в корне JSON — без обёртки fields.

Параметры

Параметр Тип Обяз. Описание
:entityTypeId (path) number да Идентификатор типа смарт-процесса. Источник: GET /v1/smart-processes — поле entityTypeId в каждом элементе массива data

Поля запроса (body)

Поле Тип Обяз. Описание
userTypeId string да Тип поля. Список допустимых значений — GET /v1/items/:entityTypeId/userfields/types. Примеры: string, enumeration, integer, double, datetime
fieldName string да Полное системное имя: префикс UF_ + entityId + _, затем суффикс. У обычного смарт-процесса entityId равен CRM_<typeId>, и имя имеет формат UF_CRM_<typeId>_<суффикс>. Здесь typeId — это поле id (внутренний ID типа) из ответа GET /v1/smart-processes, а не entityTypeId из пути запроса: значения различаются. Поле id доступно всегда, даже если у смарт-процесса ещё нет полей. У встроенного смарт-счёта entityTypeId=31, в том числе по пути /v1/userfields/invoices, entityId равен CRM_SMART_INVOICE, и имя имеет формат UF_CRM_SMART_INVOICE_<суффикс>. Готовый entityId приходит в каждом элементе ответа GET /v1/items/:entityTypeId/userfields, если у сущности уже есть поля. Авто-генерация не поддерживается: бэкенд не достраивает префикс, неполное имя даёт 422 BITRIX_ERROR
label string нет Подпись для отображения. Заполняет каждую из editFormLabel, listColumnLabel, listFilterLabel, если соответствующая подпись не передана явно. Строка преобразуется в { "ru": "значение" }. Для других языков передавайте подписи объектами с кодами языков
editFormLabel object нет Подпись в форме редактирования по языкам. Пример: { "ru": "Проект", "en": "Project" }. Значения устанавливаются для указанных языков. Остальные локали заполняются по правилам Битрикс24
listColumnLabel object нет Заголовок столбца списка по языкам. Явное значение имеет приоритет перед label
listFilterLabel object нет Подпись фильтра по языкам. Явное значение имеет приоритет перед label
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 — личный ключ

Terminal 
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-приложение

Terminal 
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 Идентификатор созданного поля. Возвращается строкой. При чтении через Получить поле то же значение приходит числом

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "id": "7119"
  }
}

Пример ответа при ошибке

422 — некорректное имя поля, оно не начинается с UF_ + entityId + _:

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_ + entityId + _
422 BITRIX_ERROR Неизвестный userTypeId (не из каталога /types), дублирующее имя поля или некорректные settings
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
401 MISSING_API_KEY Отсутствует заголовок X-Api-Key

Полный список общих ошибок API — Ошибки.

Известные особенности

Префикс имени поля смарт-счёта принимается только целиком. При создании поля встроенного смарт-счёта через POST /v1/userfields/invoices (entityId равен CRM_SMART_INVOICE) имя с частичным префиксом отклоняется:

fieldName Ответ
UF_CRM_VFY_A 422 «Некорректный код поля»
UF_CRM_TESTPREFIX253906 422 «Некорректный код поля» — одного UF_CRM_ мало
UF_SMART_INVOICE_X253906 422 «Некорректный код поля» — CRM_ обязателен
UF_CRM_SMART_INVOICE_VFYA 201 Created

Имя обязано начинаться с UF_ + entityId сущности + _. Тело запроса POST /v1/userfields/invoices с корректным именем:

JSON 
{
  "userTypeId": "string",
  "fieldName": "UF_CRM_SMART_INVOICE_VFYA"
}

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