Создать поле

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_CRM_<typeId>_<суффикс>. Здесь typeId — это поле id (внутренний ID типа) из ответа `GET /v1/smart-processes`, а не 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 — личный ключ

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_CRM_<typeId>_<суффикс>):

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

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

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