## Схема поля шаблона

`GET /v1/requisite-presets/:presetId/fields/schema`

Возвращает структуру строки поля шаблона реквизитов: типы, обязательность, флаги доступа. Используйте, чтобы узнать допустимые типы и правила перед `POST /v1/requisite-presets/:presetId/fields` или `PATCH /v1/requisite-presets/:presetId/fields/:id`.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `presetId` (path) | number | да | ID шаблона реквизитов. Получить список шаблонов: `GET /v1/requisite-presets` |

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/requisite-presets/1/fields/schema" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/requisite-presets/1/fields/schema" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

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

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

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

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

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

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

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | object | Объект с описанием схемы |
| `data.fields` | object | Словарь полей строки шаблона. Ключи — в camelCase: `id`, `fieldName` и другие |
| `data.fields.id` | object | Идентификатор строки поля. Только для чтения |
| `data.fields.fieldName` | object | Имя поля реквизита, например `RQ_INN`. Обязательно при создании. При обновлении передавать не нужно — текущее значение подставляется автоматически |
| `data.fields.fieldTitle` | object | Заголовок поля в печатной форме. Не обязателен |
| `data.fields.sort` | object | Порядок сортировки поля в шаблоне |
| `data.fields.inShortList` | object | Флаг отображения поля в кратком списке. В API представлен как `true`/`false` |

Каждое поле в `data.fields` описано объектом со следующими ключами:

| Ключ | Тип | Описание |
|------|-----|---------|
| `type` | string | Тип значения: `integer`, `string`, `char` |
| `isRequired` | boolean | Обязательно ли поле при создании |
| `isReadOnly` | boolean | Только для чтения — нельзя задать при записи |
| `isImmutable` | boolean | Нельзя изменить после создания |
| `isMultiple` | boolean | Допускает несколько значений |
| `isDynamic` | boolean | Динамическое (пользовательское) поле |
| `title` | string | Название поля для отображения, на языке портала |

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

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": {
        "type": "integer",
        "isRequired": false,
        "isReadOnly": true,
        "isImmutable": false,
        "isMultiple": false,
        "isDynamic": false,
        "title": "ID"
      },
      "fieldName": {
        "type": "string",
        "isRequired": true,
        "isReadOnly": false,
        "isImmutable": false,
        "isMultiple": false,
        "isDynamic": false,
        "title": "Имя"
      },
      "fieldTitle": {
        "type": "string",
        "isRequired": false,
        "isReadOnly": false,
        "isImmutable": false,
        "isMultiple": false,
        "isDynamic": false,
        "title": "Название в шаблоне"
      },
      "sort": {
        "type": "integer",
        "isRequired": false,
        "isReadOnly": false,
        "isImmutable": false,
        "isMultiple": false,
        "isDynamic": false,
        "title": "Сортировка"
      },
      "inShortList": {
        "type": "char",
        "isRequired": false,
        "isReadOnly": false,
        "isImmutable": false,
        "isMultiple": false,
        "isDynamic": false,
        "title": "Показывать в кратком списке"
      }
    }
  }
}
```

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

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PRESET_ID` | Переданный `presetId` не является положительным целым числом |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `crm` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

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

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

**Поле `inShortList` описано в схеме типом `char`, но API работает с булевым значением.** При записи через `POST` или `PATCH` передавайте `true`/`false`, в ответах чтения поле приходит как `true`/`false`.

**Схема объявляет `fieldName` обязательным (`isRequired: true`), но при обновлении его передавать не нужно.** При `PATCH` без `fieldName` Вайбкод получает текущее значение из Битрикс24 и подставляет его автоматически. Обязательным `fieldName` остаётся при создании через `POST`.

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

- [Поля, доступные для добавления](/docs/entities/requisite-presets/preset-fields/available)
- [Добавить поле в шаблон](/docs/entities/requisite-presets/preset-fields/create)
- [Обновить поле шаблона](/docs/entities/requisite-presets/preset-fields/update)
- [Шаблоны реквизитов](/docs/entities/requisite-presets)