[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-userfields":3,"docs-tabs-userfields":6},{"content":4,"lastmod":5},"# Пользовательские поля\n\nУправление пользовательскими полями CRM-сущностей и смарт-процессов Битрикс24: создание, обновление, удаление текстовых полей, списков, дат, чисел, привязок к сотрудникам и сущностям CRM. Изменения применяются к полям сущности на всём портале — учитывайте это при работе на боевых данных.\n\n**Скоуп:** `crm`, `userfieldconfig` | **Базовый URL:** `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1` | **Авторизация:** `X-Api-Key`\n\n[Быстрый старт](#быстрый-старт) | [Полный пример](#полный-пример) | [Справочник эндпоинтов](#справочник-эндпоинтов) | [Коды ошибок](#коды-ошибок)\n\n## Разделы документации\n\n- [Поля CRM-сущностей](\u002Fdocs\u002Fuserfields\u002Fcrm) — управление полями сделок, лидов, контактов, компаний, предложений и реквизитов\n- [Поля смарт-процессов](\u002Fdocs\u002Fuserfields\u002Fsmart-processes) — управление полями элементов смарт-процессов по `entityTypeId`\n\n---\n\n## Быстрый старт\n\n### 1. Посмотрите существующие поля сделки\n\n```bash\ncurl -H \"X-Api-Key: YOUR_API_KEY\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fuserfields\u002Fdeals\"\n```\n\nОтвет:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 7115,\n      \"entityId\": \"CRM_DEAL\",\n      \"fieldName\": \"UF_CRM_PROJECT_CODE\",\n      \"userTypeId\": \"string\",\n      \"mandatory\": \"N\",\n      \"sort\": \"100\",\n      \"editFormLabel\": { \"ru\": \"Код проекта\" }\n    }\n  ],\n  \"meta\": { \"total\": 44 }\n}\n```\n\n### 2. Создайте новое поле\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fuserfields\u002Fdeals\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"userTypeId\": \"string\",\n    \"fieldName\": \"PROJECT_CODE\",\n    \"label\": \"Код проекта\"\n  }'\n```\n\nПри успешном создании возвращается HTTP `201 Created` с числовым `id` нового поля.\n\n---\n\n## Полный пример\n\nСценарий: добавить поле-список «Источник лида», получить его полное описание, сделать видимым в фильтре, удалить.\n\n```javascript\nconst KEY = process.env.VIBECODE_API_KEY\nconst BASE = 'https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1'\n\nasync function api(method, path, body) {\n  const opts = { method, headers: { 'X-Api-Key': KEY } }\n  if (body) {\n    opts.headers['Content-Type'] = 'application\u002Fjson'\n    opts.body = JSON.stringify(body)\n  }\n  const res = await fetch(`${BASE}${path}`, opts)\n  return res.status === 204 ? null : res.json()\n}\n\n\u002F\u002F 1. Узнать, сколько пользовательских полей уже создано\nconst before = await api('GET', '\u002Fuserfields\u002Fdeals')\nconsole.log(`Полей до создания: ${before.meta.total}`)\n\n\u002F\u002F 2. Создать поле-список «Источник лида»\nconst created = await api('POST', '\u002Fuserfields\u002Fdeals', {\n  userTypeId: 'enumeration',\n  fieldName: 'LEAD_SOURCE',\n  label: 'Источник лида',\n  mandatory: 'Y',\n  list: [\n    { VALUE: 'Сайт', SORT: 10 },\n    { VALUE: 'Соцсети', SORT: 20 },\n    { VALUE: 'Реклама', SORT: 30 }\n  ]\n})\nconst newId = created.data.id\nconsole.log('Создано поле с id:', newId)\n\n\u002F\u002F 3. Получить полное описание созданного поля\nconst detail = await api('GET', `\u002Fuserfields\u002Fdeals\u002F${newId}`)\nconsole.log('Варианты списка:', detail.data.list.map(v => v.VALUE).join(', '))\n\n\u002F\u002F 4. Сделать поле видимым в фильтре карточки\nawait api('PATCH', `\u002Fuserfields\u002Fdeals\u002F${newId}`, { showFilter: 'Y' })\n\n\u002F\u002F 5. Удалить поле — ответ HTTP 204 с пустым телом\nawait api('DELETE', `\u002Fuserfields\u002Fdeals\u002F${newId}`)\nconsole.log('Поле удалено')\n```\n\n---\n\n## Справочник эндпоинтов\n\n### Поля CRM-сущностей\n\n| Метод | Путь | Bitrix24 метод | Описание |\n|-------|------|----------------|---------|\n| GET | [\u002Fv1\u002Fuserfields\u002F:entity](\u002Fdocs\u002Fuserfields\u002Fcrm\u002Flist) | crm.:entity.userfield.list | Список полей сущности |\n| GET | [\u002Fv1\u002Fuserfields\u002F:entity\u002Ftypes](\u002Fdocs\u002Fuserfields\u002Fcrm\u002Ftypes) | crm.userfield.types | Каталог типов полей |\n| GET | [\u002Fv1\u002Fuserfields\u002F:entity\u002F:id](\u002Fdocs\u002Fuserfields\u002Fcrm\u002Fget) | crm.:entity.userfield.get | Одно поле по идентификатору |\n| POST | [\u002Fv1\u002Fuserfields\u002F:entity](\u002Fdocs\u002Fuserfields\u002Fcrm\u002Fcreate) | crm.:entity.userfield.add | Создать поле |\n| PATCH | [\u002Fv1\u002Fuserfields\u002F:entity\u002F:id](\u002Fdocs\u002Fuserfields\u002Fcrm\u002Fupdate) | crm.:entity.userfield.update | Обновить поле |\n| DELETE | [\u002Fv1\u002Fuserfields\u002F:entity\u002F:id](\u002Fdocs\u002Fuserfields\u002Fcrm\u002Fdelete) | crm.:entity.userfield.delete | Удалить поле |\n\n`:entity` — одно из значений: `deals`, `leads`, `contacts`, `companies`, `quotes`, `requisites`.\n\n### Поля смарт-процессов\n\n| Метод | Путь | Bitrix24 метод | Описание |\n|-------|------|----------------|---------|\n| GET | [\u002Fv1\u002Fitems\u002F:entityTypeId\u002Fuserfields](\u002Fdocs\u002Fuserfields\u002Fsmart-processes\u002Flist) | userfieldconfig.list | Список полей смарт-процесса |\n| GET | [\u002Fv1\u002Fitems\u002F:entityTypeId\u002Fuserfields\u002Ftypes](\u002Fdocs\u002Fuserfields\u002Fsmart-processes\u002Ftypes) | crm.userfield.types | Каталог типов полей |\n| GET | [\u002Fv1\u002Fitems\u002F:entityTypeId\u002Fuserfields\u002F:id](\u002Fdocs\u002Fuserfields\u002Fsmart-processes\u002Fget) | userfieldconfig.get | Одно поле по идентификатору |\n| POST | [\u002Fv1\u002Fitems\u002F:entityTypeId\u002Fuserfields](\u002Fdocs\u002Fuserfields\u002Fsmart-processes\u002Fcreate) | userfieldconfig.add | Создать поле |\n| PATCH | [\u002Fv1\u002Fitems\u002F:entityTypeId\u002Fuserfields\u002F:id](\u002Fdocs\u002Fuserfields\u002Fsmart-processes\u002Fupdate) | userfieldconfig.update | Обновить поле |\n| DELETE | [\u002Fv1\u002Fitems\u002F:entityTypeId\u002Fuserfields\u002F:id](\u002Fdocs\u002Fuserfields\u002Fsmart-processes\u002Fdelete) | userfieldconfig.delete | Удалить поле |\n\n`entityTypeId` — идентификатор типа смарт-процесса из ответа [`GET \u002Fv1\u002Fsmart-processes`](\u002Fdocs\u002Fentities\u002Fsmart-processes).\n\n---\n\n## Коды ошибок\n\n### Ошибки пользовательских полей\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 400 | `UNKNOWN_ENTITY` | Сущность не из списка поддерживаемых (`deals`, `leads`, `contacts`, `companies`, `quotes`, `requisites`) |\n| 400 | `INVALID_ENTITY_TYPE_ID` | `entityTypeId` смарт-процесса не является положительным целым числом |\n| 400 | `MISSING_FIELD` | Не передан обязательный параметр `userTypeId` при создании |\n| 400 | `INVALID_REQUEST` | Тело запроса не является объектом |\n| 403 | `BITRIX_ACCESS_DENIED` | OAuth-приложению Битрикс24 не хватает прав на `userfieldconfig.*` для смарт-процессов |\n| 404 | `ENTITY_NOT_FOUND` | Поле с указанным `id` не существует |\n| 404 | `SMART_PROCESS_NOT_FOUND` | Смарт-процесс с указанным `entityTypeId` не найден на портале |\n| 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос — некорректное значение, недопустимое имя поля, неизвестный `userTypeId` |\n\n### Системные ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 401 | `MISSING_API_KEY` | Отсутствует заголовок `X-Api-Key` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `crm` |\n| 502 | `BITRIX_UNAVAILABLE` | Портал Битрикс24 недоступен |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n---\n\n## Смотрите также\n\n- [Поля CRM-сущностей](\u002Fdocs\u002Fuserfields\u002Fcrm)\n- [Поля смарт-процессов](\u002Fdocs\u002Fuserfields\u002Fsmart-processes)\n- [Смарт-процессы](\u002Fdocs\u002Fentities\u002Fsmart-processes)\n- [Сделки](\u002Fdocs\u002Fentities\u002Fdeals)\n- [Реквизиты](\u002Fdocs\u002Fentities\u002Frequisites)\n- [Ошибки](\u002Fdocs\u002Ferrors)\n","2026-07-07",{}]