## Поля головного товара

`GET /v1/catalog-skus/fields`

Возвращает справочник полей головного товара с подписями, типами, признаками доступности на чтение и запись, описаниями и словарями `enum` там, где набор значений фиксирован, список полей для группировки в агрегации и операции, доступные в пакетном запросе.

Поля `dateCreate`, `timestampX`, `dateActiveFrom` и `dateActiveTo` не принимаются в `filter`: запрос возвращает `400 UNKNOWN_FILTER_FIELD` до обращения к Битрикс24. Эти даты можно запрашивать через `select` и читать в ответе.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `iblockId` (query) | number | нет | ID информационного блока товарного каталога: поле `catalogs[].iblockId` из [`GET /v1/catalogs`](/docs/entities/catalogs), а не `catalogs[].id` записи каталога. С ним справочник дополняется свойствами каталога `propertyNNN` и полем `priceType`. Без него, а также с `iblockId` каталога вариаций или несуществующего каталога приходят 24 статических поля и предупреждение `fields_partial` в `meta.warnings` |

В примерах `iblockId=25` — значение `catalogs[].iblockId` товарного каталога. Если у записи каталога `id` отличается, подставьте значение `iblockId`.

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/catalog-skus/fields?iblockId=25" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/catalog-skus/fields?iblockId=25" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

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

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)
```

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

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

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

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

`data.fields` — объект, ключ которого совпадает с именем поля, а значение содержит тип, признаки доступности на запись, подпись для отображения и — у полей с фиксированным набором значений — их словарь. Состав ключей разобран в таблице после списка полей. `data.aggregatable` — поля для `groupBy` в [агрегации](./aggregate.md). `data.batch` — операции, доступные в [пакетном запросе](/docs/batch).

| Поле | Тип | RO | Описание |
|------|-----|:--:|---------|
| `id` | number | да | Идентификатор головного товара |
| `name` | string | нет | Название головного товара. Обязательно при создании |
| `active` | boolean | нет | Активен ли товар |
| `iblockId` | number | нет¹ | ID товарного каталога. Список: [`GET /v1/catalogs`](/docs/entities/catalogs). Обязателен при создании, задаётся только при создании |
| `iblockSectionId` | number \| null | нет | ID основного раздела каталога. `null` — товар не привязан к разделу. Список: [`GET /v1/catalog-sections`](/docs/entities/catalog-sections) |
| `available` | boolean | да | Доступен ли товар к покупке. Вычисляется Битрикс24 |
| `bundle` | boolean | да | Является ли товар набором. Вычисляется Битрикс24 |
| `dateActiveFrom` | datetime | нет | Дата начала активности. В фильтре не принимается (`400 UNKNOWN_FILTER_FIELD`) |
| `dateActiveTo` | datetime | нет | Дата окончания активности. В фильтре не принимается (`400 UNKNOWN_FILTER_FIELD`) |
| `createdBy` | number | да | ID пользователя, создавшего товар. Список: [`GET /v1/users`](/docs/entities/users) |
| `modifiedBy` | number | да | ID пользователя, изменившего товар последним. Список: [`GET /v1/users`](/docs/entities/users) |
| `dateCreate` | datetime | да | Дата создания. В фильтре не принимается (`400 UNKNOWN_FILTER_FIELD`) |
| `timestampX` | datetime | да | Дата последнего изменения. В фильтре не принимается (`400 UNKNOWN_FILTER_FIELD`) |
| `code` | string \| null | нет | Символьный код товара. `null`, если не задан |
| `xmlId` | string | нет | Внешний код |
| `previewText` | string | нет | Текст анонса |
| `detailText` | string | нет | Подробное описание |
| `previewTextType` | string | нет | Формат текста анонса: `text` или `html` |
| `detailTextType` | string | нет | Формат подробного описания: `text` или `html` |
| `sort` | number | нет | Порядок сортировки |
| `previewPicture` | object \| null | нет | Картинка анонса. В ответе — объект `{ id, url, urlMachine }` или `null`. По полю нельзя фильтровать и сортировать |
| `detailPicture` | object \| null | нет | Детальная картинка, тот же формат. По полю нельзя фильтровать и сортировать |
| `iblockSection` | object | нет | Массив ID всех разделов товара. Принимается при создании и изменении. В ответах `get`, `create` и `update` приходит массивом или `null`. В список и поиск не попадает и в `select` не поддерживается — имя отвечает предупреждением `UNKNOWN_SELECT_FIELD`. Список: [`GET /v1/catalog-sections`](/docs/entities/catalog-sections) |
| `type` | number | да | Тип товара, вычисляется Битрикс24: `6` — головной товар без вариаций, `3` — с вариациями. В фильтре принимается одно точное число `3` или `6` |

¹ `iblockId` доступен для записи только при создании — в справочнике приходит с `readonly: false` и `createOnly: true`.

С `iblockId` товарного каталога в `data.fields` добавляются поле `priceType` с типом `char` и свойства каталога `propertyNNN` с типом `productproperty`. Названия и типы свойств — в [`GET /v1/catalog-product-properties`](/docs/entities/catalog-product-properties).

Заголовками запроса язык подписей и описаний не переключается. У значений `enum` подпись `label` английская, русская приходит отдельным ключом.

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.fields.<имя>.type` | string | Тип поля: `number`, `string`, `boolean`, `datetime`, `object`. У свойств каталога — `productproperty` |
| `data.fields.<имя>.label` | string | Подпись поля. У статических полей — на русском, у свойств каталога совпадает с именем поля |
| `data.fields.<имя>.description` | string | Расширенное описание поля: назначение, где взять список допустимых значений, поведение при записи |
| `data.fields.<имя>.readonly` | boolean | `true` — поле заполняется системой и не принимается при создании и изменении |
| `data.fields.<имя>.required` | boolean | `true` — поле обязательно при создании (`name`, `iblockId`). Ключ присутствует только у таких полей |
| `data.fields.<имя>.createOnly` | boolean | `true` — поле принимается только при создании. В `PATCH` отклоняется с `READONLY_FIELD` (есть у `iblockId`) |
| `data.fields.<имя>.writeOnly` | boolean | `true` — поле принимается на запись и не возвращается в списке и поиске (есть у `iblockSection`) |
| `data.fields.<имя>.notReturned` | boolean | `true` — имя не поддерживается в `select` (есть у `iblockSection`) |
| `data.fields.<имя>.nullable` | boolean | `true` — поле может прийти со значением `null`. Ключ присутствует только у таких полей |
| `data.fields.<имя>.multiple` | boolean | `true` — свойство каталога хранит несколько значений и приходит массивом. Ключ присутствует только у таких свойств |
| `data.fields.<имя>.enum` | array | Словарь допустимых значений: массив `{ value, label }`. Ключ есть у `previewTextType` и `detailTextType`. Отправлять нужно `value`, `label` предназначен для показа человеку |
| `data.aggregatable` | string[] | Поля для `groupBy` в [агрегации](./aggregate.md): `iblockSectionId` |
| `data.batch` | string[] | Операции головного товара, доступные в [пакетном запросе](/docs/batch): `create`, `update`, `delete` |
| `meta.warnings` | array | Приходит без `iblockId` товарного каталога: элемент `{ code: "fields_partial", message }` — в ответе только статические поля |

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

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": {
        "type": "number",
        "readonly": true,
        "label": "Идентификатор товара",
        "description": "Уникальный идентификатор товара каталога."
      },
      "iblockId": {
        "type": "number",
        "readonly": false,
        "createOnly": true,
        "required": true,
        "label": "ID каталога",
        "description": "Каталог, которому принадлежит товар. Список: GET /v1/catalogs. Задаётся только при создании — смена через PATCH отклоняется, товар нельзя перенести между каталогами."
      },
      "code": {
        "type": "string",
        "readonly": false,
        "nullable": true,
        "label": "Символьный код",
        "description": "Символьный код товара; null, если не задан."
      },
      "iblockSection": {
        "type": "object",
        "readonly": false,
        "writeOnly": true,
        "notReturned": true,
        "label": "Разделы каталога",
        "description": "Массив ID разделов каталога, к которым относится товар. Принимается только при создании и обновлении — на чтении основной раздел приходит скаляром iblockSectionId. Список: GET /v1/catalog-sections."
      },
      "previewTextType": {
        "type": "string",
        "readonly": false,
        "label": "Формат текста анонса",
        "description": "Формат поля previewText.",
        "enum": [
          { "value": "text", "label": "Plain text", "labelRu": "Текст" },
          { "value": "html", "label": "HTML", "labelRu": "HTML" }
        ]
      },
      "type": {
        "type": "number",
        "readonly": true,
        "label": "Тип товара Битрикс24",
        "description": "Вычисляется Битрикс24. Новый головной товар сначала пустой SKU; тип меняется после привязки вариаций. В фильтре принимается только точный тип 3 или 6."
      },
      "property293": {
        "type": "productproperty",
        "readonly": false,
        "multiple": true,
        "label": "property293"
      }
    },
    "aggregatable": [
      "iblockSectionId"
    ],
    "batch": [
      "create",
      "update",
      "delete"
    ]
  }
}
```

Пример сокращён до семи полей — по одному на признаки `readonly`, `createOnly` с `required`, `nullable`, пару `writeOnly` + `notReturned`, словарь `enum`, вычисляемый тип и свойство каталога с `multiple`. В ответе приходят все 24 статических поля, а с `iblockId` товарного каталога — ещё `priceType` и все свойства каталога.

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

403 — у ключа нет скоупа `catalog`:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'catalog' scope",
    "hint": "This request needs the 'catalog' scope, which the calling key does not carry. Add 'catalog' to this key in the developer cabinet (or through the management API), then repeat the call.",
    "cause": "key_scope_missing",
    "requiredScope": "catalog",
    "keyScopes": ["task", "im"],
    "fix": { "action": "edit_key_scopes", "via": "cabinet" },
    "userMessage": "Ключу приложения не хватает права «Товарный каталог». Добавить его можно в настройках ключа в кабинете разработчика."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `catalog` |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 429 | `RATE_LIMITED` | Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке `x-ratelimit-limit` (потолок делится на реплики). Повторите после срока из заголовка `Retry-After` |

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

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

**Часть полей не приходит в списке по умолчанию.** Символьный код `code`, внешний код `xmlId`, сортировка `sort`, тексты `previewText`, `detailText` с их форматами и картинки не возвращаются в ответе `GET /v1/catalog-skus` без явного `select`. Перечислите нужные имена в `select`, чтобы получить их в списке. В ответе одного товара `GET /v1/catalog-skus/:id` они возвращаются всегда.

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

- [Список головных товаров](/docs/entities/catalog-skus/list)
- [Создать головной товар](/docs/entities/catalog-skus/create)
- [Поиск головных товаров](/docs/entities/catalog-skus/search)
- [Агрегация головных товаров](/docs/entities/catalog-skus/aggregate)
- [Свойства товаров каталога](/docs/entities/catalog-product-properties)
- [Справочник API](/docs/api-reference)