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

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

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

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

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

- [Поля CRM-сущностей](/docs/userfields/crm) — управление полями сделок, лидов, контактов, компаний, предложений и реквизитов
- [Поля смарт-процессов](/docs/userfields/smart-processes) — управление полями элементов смарт-процессов по `entityTypeId`

## Значения полей в записях

Эндпоинты этого раздела управляют самим полем — его типом, подписью и настройками. Значение поля в конкретной записи читается и записывается вместе с самой записью: `POST /v1/deals`, `PATCH /v1/deals/:id`, `GET /v1/deals/:id`.

Имя, под которым поле принимается в этих запросах, отличается от значения `fieldName`, которое возвращают эндпоинты этого раздела. Поле, созданное на сделках как `fieldName: "PROJECT_CODE"`, стоит в списке определений под именем `UF_CRM_PROJECT_CODE`, а в схеме сделки — под именем `ufCrmProjectCode`. Рабочее имя всегда берётся из `GET /v1/{entity}/fields`. Формат значения для каждого из типов, множественные поля и очистка — [Пользовательские поля (UF)](/docs/entity-api#пользовательские-поля-uf).

---

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

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

```bash
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. Создайте новое поле

```bash
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](/docs/userfields/crm/list) | crm.:entity.userfield.list | Список полей сущности |
| GET | [/v1/userfields/:entity/types](/docs/userfields/crm/types) | crm.userfield.types | Каталог типов полей |
| GET | [/v1/userfields/:entity/:id](/docs/userfields/crm/get) | crm.:entity.userfield.get | Одно поле по идентификатору |
| POST | [/v1/userfields/:entity](/docs/userfields/crm/create) | crm.:entity.userfield.add | Создать поле |
| PATCH | [/v1/userfields/:entity/:id](/docs/userfields/crm/update) | crm.:entity.userfield.update | Обновить поле |
| DELETE | [/v1/userfields/:entity/:id](/docs/userfields/crm/delete) | crm.:entity.userfield.delete | Удалить поле |

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

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

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

`entityTypeId` — идентификатор типа смарт-процесса из ответа [`GET /v1/smart-processes`](/docs/entities/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 — [Ошибки](/docs/errors).

---

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

- [Поля CRM-сущностей](/docs/userfields/crm)
- [Поля смарт-процессов](/docs/userfields/smart-processes)
- [Обзор API](/docs/entity-api)
- [Смарт-процессы](/docs/entities/smart-processes)
- [Сделки](/docs/entities/deals)
- [Реквизиты](/docs/entities/requisites)
- [Ошибки](/docs/errors)