## Поля контракта формы

`GET /v1/crm-forms/fields`

Возвращает схему свойств верхнего уровня CRM-формы. По ней проверяют, какие блоки конфигурации входят в контракт формы, перед созданием или изменением формы.

## Параметры

| Параметр | Тип | Описание |
|----------|-----|----------|
| `select` (query) | string | Свойства метаданных через запятую, например `name,type,multiple`. Без параметра возвращаются все свойства метаданных |

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/crm-forms/fields" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/crm-forms/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Свойств формы:', data.length)
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-forms/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Описания свойств формы. Состав свойств — в таблице ниже |
| `data[].name` | string | Имя свойства формы |
| `data[].type` | string | Тип значения: `int`, `string`, `bool`, `date-time` или `object` |
| `data[].elementType` | string \| null | Тип элемента у множественного свойства, например `object`. `null` у одиночных свойств |
| `data[].multiple` | boolean | `true` — значение свойства массив |
| `data[].title` | string | Подпись свойства. Совпадает с `name` |
| `data[].description` | string \| null | Описание свойства |
| `data[].validationRules` | array | Правила проверки значения |
| `data[].requiredGroups` | array \| null | Группы обязательности |
| `data[].filterable` | boolean | Отмечено ли свойство как фильтруемое |
| `data[].sortable` | boolean | Отмечено ли свойство как сортируемое |
| `data[].editable` | boolean | Признак изменяемости из схемы. Приходит `false` у всех свойств, записываемые свойства проверяет Битрикс24 при сохранении формы |

Свойства формы в `data`:

| Поле | Тип | RO | Описание |
|------|-----|:--:|---------|
| `id` | int | да | Идентификатор формы. Список: [`GET /v1/crm-forms`](/docs/entities/crm-forms/list) |
| `code` | string | да | Символьный код формы |
| `name` | string | | Название формы |
| `active` | bool | | Включена ли форма. Передаётся только при создании. У существующей формы меняется через [включение](/docs/entities/crm-forms/activate) и [выключение](/docs/entities/crm-forms/deactivate) |
| `system` | bool | да | Системная форма |
| `languageId` | string | | Язык формы. Список: `data.languages[].id` в [конфигурации конструктора](/docs/entities/crm-forms/configuration) |
| `templateId` | string | | Шаблон формы |
| `createdTime` | date-time | да | Время создания |
| `updatedTime` | date-time | да | Время последнего изменения. Передаётся в [изменении формы](/docs/entities/crm-forms/update) как версия для защиты от перезаписи чужих изменений |
| `activeChangedById` | int | да | Кто последним менял активность. Список: [`GET /v1/users`](/docs/entities/users) |
| `activeChangedTime` | date-time | да | Когда последний раз менялась активность |
| `appearance` | object | | Оформление: заголовок, описание, подпись и цвета кнопки |
| `crm` | object | | Привязка к CRM: схема сущностей, режим дублей, воронка. Значения — в [конфигурации конструктора](/docs/entities/crm-forms/configuration) |
| `dependencies` | object | | Массив правил зависимости полей, `multiple: true` |
| `presetFields` | object | | Массив предустановленных значений полей, `multiple: true` |
| `responsible` | object | | Ответственные за результаты формы и учёт рабочего времени. ID ответственных — из [`GET /v1/users`](/docs/entities/users) |
| `agreements` | object | | Соглашения, которые посетитель принимает при отправке |
| `submission` | object | | Действия после отправки: тексты и адреса перехода при успехе и ошибке |
| `payment` | object | | Настройки оплаты |
| `callback` | object | | Настройки обратного звонка |
| `booking` | object | | Настройки бронирования |
| `analytics` | object | | Настройки аналитики |
| `spamProtection` | object | | Настройки защиты от спама |
| `integrations` | object | | Настройки интеграций |
| `fields` | object | | Массив полей формы, `multiple: true`. Имена полей — из [`GET /v1/crm-forms/entity-fields`](/docs/entities/crm-forms/entity-fields) |

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

```json
{
  "success": true,
  "data": [
    {"name": "id", "type": "int", "elementType": null, "multiple": false, "title": "id", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": true, "editable": false},
    {"name": "code", "type": "string", "elementType": null, "multiple": false, "title": "code", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": false, "editable": false},
    {"name": "name", "type": "string", "elementType": null, "multiple": false, "title": "name", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": true, "editable": false},
    {"name": "active", "type": "bool", "elementType": null, "multiple": false, "title": "active", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": true, "editable": false},
    {"name": "system", "type": "bool", "elementType": null, "multiple": false, "title": "system", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "languageId", "type": "string", "elementType": null, "multiple": false, "title": "languageId", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "templateId", "type": "string", "elementType": null, "multiple": false, "title": "templateId", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "createdTime", "type": "date-time", "elementType": null, "multiple": false, "title": "createdTime", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": true, "editable": false},
    {"name": "updatedTime", "type": "date-time", "elementType": null, "multiple": false, "title": "updatedTime", "description": null, "validationRules": [], "requiredGroups": null, "filterable": true, "sortable": true, "editable": false},
    {"name": "activeChangedById", "type": "int", "elementType": null, "multiple": false, "title": "activeChangedById", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "activeChangedTime", "type": "date-time", "elementType": null, "multiple": false, "title": "activeChangedTime", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "appearance", "type": "object", "elementType": null, "multiple": false, "title": "appearance", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "crm", "type": "object", "elementType": null, "multiple": false, "title": "crm", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "dependencies", "type": "object", "elementType": "object", "multiple": true, "title": "dependencies", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "presetFields", "type": "object", "elementType": "object", "multiple": true, "title": "presetFields", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "responsible", "type": "object", "elementType": null, "multiple": false, "title": "responsible", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "agreements", "type": "object", "elementType": null, "multiple": false, "title": "agreements", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "submission", "type": "object", "elementType": null, "multiple": false, "title": "submission", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "payment", "type": "object", "elementType": null, "multiple": false, "title": "payment", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "callback", "type": "object", "elementType": null, "multiple": false, "title": "callback", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "booking", "type": "object", "elementType": null, "multiple": false, "title": "booking", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "analytics", "type": "object", "elementType": null, "multiple": false, "title": "analytics", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "spamProtection", "type": "object", "elementType": null, "multiple": false, "title": "spamProtection", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "integrations", "type": "object", "elementType": null, "multiple": false, "title": "integrations", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false},
    {"name": "fields", "type": "object", "elementType": "object", "multiple": true, "title": "fields", "description": null, "validationRules": [], "requiredGroups": null, "filterable": false, "sortable": false, "editable": false}
  ]
}
```

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

400 — передан неизвестный параметр запроса:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Unknown query parameter"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | Передан неизвестный параметр запроса |
| 400 | `INVALID_PARAMS` | `select` не является строкой или массивом строк |
| 400 | `INVALID_PARAMS` | Битрикс24 отклонил проекцию. Исходный код — в `error.b24Code` |
| 403 | `BITRIX_ACCESS_DENIED` | У пользователя Битрикс24 нет прав на формы |
| 403 | `BITRIX_INSUFFICIENT_SCOPE` | У токена Битрикс24 нет необходимого скоупа |
| 404 | `ENTITY_NOT_FOUND` | Портал не нашёл запрошенную сущность или описание поля. Исходный код — `error.b24Code` |
| 409 | `CRM_FORM_REST_NOT_ENABLED` | REST-методы CRM-форм недоступны на этом портале Битрикс24. Это не означает отсутствие отдельной формы |
| 400–599 | `CRM_FORM_*` | Отказ по правилам форм. Код и HTTP-статус сохранены, исходный код — в `error.b24Code` |
| 422 | `BITRIX_ERROR` | Другой отказ Битрикс24. Причина — в `error.message`, исходный код — в `error.b24Code` |
| 429 | `RATE_LIMITED` | Превышена частота запросов. Учитывайте заголовок `Retry-After` |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 вернул ответ в неожиданном виде |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен: ошибка сервера или разрыв соединения |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 не ответил вовремя. Чтение можно повторить |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `TOKEN_MISSING` | У ключа не настроен доступ к Битрикс24 |
| 403 | `SCOPE_DENIED` | У API-ключа Вайбкод нет скоупа `crm` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

Этот справочник описывает свойства самой формы. CRM-поля и варианты их значений перечисляет отдельный [Список полей сущностей](/docs/entities/crm-forms/entity-fields). Это разные справочники.

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

- [Получить поле контракта формы](/docs/entities/crm-forms/field)
- [Создать форму](/docs/entities/crm-forms/create)
- [Изменить форму](/docs/entities/crm-forms/update)
- [Получить форму](/docs/entities/crm-forms/get)
- [Получить конфигурацию конструктора](/docs/entities/crm-forms/configuration)
- [CRM-формы](/docs/entities/crm-forms)