#Пользовательские поля

Управление пользовательскими полями CRM-сущностей и смарт-процессов Битрикс24: создание, обновление, удаление текстовых полей, списков, дат, чисел, привязок к сотрудникам и сущностям CRM. Изменения применяются к полям сущности на всём портале — учитывайте это при работе на боевых данных.

Скоуп: crm | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Быстрый старт | Полный пример | Справочник эндпоинтов | Коды ошибок

#Разделы документации

#Быстрый старт

#1. Посмотрите существующие поля сделки

Terminal 
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/userfields/deals"

Ответ:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 7115,
      "entityId": "CRM_DEAL",
      "fieldName": "UF_CRM_PROJECT_CODE",
      "userTypeId": "string",
      "mandatory": "N",
      "sort": "100",
      "editFormLabel": { "ru": "Код проекта" }
    }
  ],
  "meta": { "total": 44 }
}

#2. Создайте новое поле

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/userfields/deals" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userTypeId": "string",
    "fieldName": "PROJECT_CODE",
    "label": "Код проекта"
  }'

При успешном создании возвращается HTTP 201 Created с числовым id нового поля.

#Полный пример

Сценарий: добавить поле-список «Источник лида», получить его полное описание, сделать видимым в фильтре, удалить.

javascript 
const KEY = process.env.VIBECODE_API_KEY
const BASE = 'https://vibecode.bitrix24.tech/v1'

async function api(method, path, body) {
  const opts = { method, headers: { 'X-Api-Key': KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  return res.status === 204 ? null : res.json()
}

// 1. Узнать, сколько пользовательских полей уже создано
const before = await api('GET', '/userfields/deals')
console.log(`Полей до создания: ${before.meta.total}`)

// 2. Создать поле-список «Источник лида»
const created = await api('POST', '/userfields/deals', {
  userTypeId: 'enumeration',
  fieldName: 'LEAD_SOURCE',
  label: 'Источник лида',
  mandatory: 'Y',
  list: [
    { VALUE: 'Сайт', SORT: 10 },
    { VALUE: 'Соцсети', SORT: 20 },
    { VALUE: 'Реклама', SORT: 30 }
  ]
})
const newId = created.data.id
console.log('Создано поле с id:', newId)

// 3. Получить полное описание созданного поля
const detail = await api('GET', `/userfields/deals/${newId}`)
console.log('Варианты списка:', detail.data.list.map(v => v.VALUE).join(', '))

// 4. Сделать поле видимым в фильтре карточки
await api('PATCH', `/userfields/deals/${newId}`, { showFilter: 'Y' })

// 5. Удалить поле — ответ HTTP 204 с пустым телом
await api('DELETE', `/userfields/deals/${newId}`)
console.log('Поле удалено')

#Справочник эндпоинтов

#Поля CRM-сущностей

Метод Путь Bitrix24 метод Описание
GET /v1/userfields/:entity crm.:entity.userfield.list Список полей сущности
GET /v1/userfields/:entity/types crm.userfield.types Каталог типов полей
GET /v1/userfields/:entity/:id crm.:entity.userfield.get Одно поле по идентификатору
POST /v1/userfields/:entity crm.:entity.userfield.add Создать поле
PATCH /v1/userfields/:entity/:id crm.:entity.userfield.update Обновить поле
DELETE /v1/userfields/:entity/:id crm.:entity.userfield.delete Удалить поле

:entity — одно из значений: deals, leads, contacts, companies, quotes, requisites.

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

Метод Путь Bitrix24 метод Описание
GET /v1/items/:entityTypeId/userfields userfieldconfig.list Список полей смарт-процесса
GET /v1/items/:entityTypeId/userfields/types crm.userfield.types Каталог типов полей
GET /v1/items/:entityTypeId/userfields/:id userfieldconfig.get Одно поле по идентификатору
POST /v1/items/:entityTypeId/userfields userfieldconfig.add Создать поле
PATCH /v1/items/:entityTypeId/userfields/:id userfieldconfig.update Обновить поле
DELETE /v1/items/:entityTypeId/userfields/:id userfieldconfig.delete Удалить поле

entityTypeId — идентификатор типа смарт-процесса из ответа `GET /v1/smart-processes`.

#Коды ошибок

#Ошибки пользовательских полей

HTTP Код Описание
400 UNKNOWN_ENTITY Сущность не из списка поддерживаемых (deals, leads, contacts, companies, quotes, requisites)
400 INVALID_ENTITY_TYPE_ID entityTypeId смарт-процесса не является положительным целым числом
400 MISSING_FIELD Не передан обязательный параметр userTypeId при создании
400 INVALID_REQUEST Тело запроса не является объектом
403 BITRIX_ACCESS_DENIED OAuth-приложению Битрикс24 не хватает прав на userfieldconfig.* для смарт-процессов
404 ENTITY_NOT_FOUND Поле с указанным id не существует
404 SMART_PROCESS_NOT_FOUND Смарт-процесс с указанным entityTypeId не найден на портале
422 BITRIX_ERROR Битрикс24 отклонил запрос — некорректное значение, недопустимое имя поля, неизвестный userTypeId

#Системные ошибки

HTTP Код Описание
401 MISSING_API_KEY Отсутствует заголовок X-Api-Key
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
403 SCOPE_DENIED API-ключ не имеет скоупа crm
502 BITRIX_UNAVAILABLE Портал Битрикс24 недоступен

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

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