## Поля услуги

`GET /v1/catalog-services/fields`

Возвращает справочник полей услуги каталога с подписями, типами, признаками записи и словарями допустимых значений, а также поля для агрегации и операции пакетного запроса.

Справочник содержит 28 статических полей услуги. Укажите `?iblockId=<ID каталога>`, чтобы при успешном ответе Битрикс24 получить также свойства каталога вида `propertyNNN`. ID каталога можно получить в [`GET /v1/catalogs`](/docs/entities/catalogs/list). Значения свойств приходят в ответе [`GET /v1/catalog-services/:id`](./get.md), названия и типы доступны также в [`GET /v1/catalog-product-properties`](/docs/entities/catalog-product-properties/list).

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

## Параметры

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

## Примеры

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

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

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

```bash
curl "https://vibecode.bitrix24.tech/v1/catalog-services/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-services/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-services/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 | нет | Активна ли услуга |
| `available` | boolean | нет | Доступна ли услуга к покупке. Без явного значения услуга создаётся с `false` |
| `iblockId` | number | нет¹ | ID товарного каталога. Список: [`GET /v1/catalogs`](/docs/entities/catalogs/list). Обязателен при создании, задаётся только при создании |
| `type` | number | да | Тип записи, у услуги всегда `7`. Заполняется Битрикс24 |
| `iblockSectionId` | number \| null | нет | ID основного раздела каталога. `null` — услуга не привязана к разделу. Список: [`GET /v1/catalog-sections`](/docs/entities/catalog-sections/list) |
| `iblockSection` | object | нет | Массив ID всех разделов каталога, к которым относится услуга. Приходит в ответе одной услуги, в `select` списка не поддерживается. Список: [`GET /v1/catalog-sections`](/docs/entities/catalog-sections/list) |
| `measure` | number | нет | ID единицы измерения. Список: [`GET /v1/catalog-measures`](/docs/entities/catalog-measures/list) |
| `vatIncluded` | boolean | нет | НДС включён в цену |
| `vatId` | number | нет | ID ставки НДС. Список: [`GET /v1/catalog-vat-rates`](/docs/entities/catalog-vat-rates/list) |
| `bundle` | boolean | да | Является ли услуга набором. Вычисляется Битрикс24 |
| `code` | string \| null | нет | Символьный код. `null`, если не задан |
| `xmlId` | string | нет | Внешний идентификатор. Если не задан, равен `id` услуги строкой |
| `sort` | number | нет | Порядок сортировки. По умолчанию `500` |
| `dateActiveFrom` | datetime | нет | Дата начала активности. В фильтре не принимается (`400 UNKNOWN_FILTER_FIELD`) |
| `dateActiveTo` | datetime | нет | Дата окончания активности. В фильтре не принимается (`400 UNKNOWN_FILTER_FIELD`) |
| `createdBy` | number | да | ID пользователя, создавшего услугу. Список: [`GET /v1/users`](/docs/entities/users/list) |
| `modifiedBy` | number | да | ID пользователя, изменившего услугу последним. Список: [`GET /v1/users`](/docs/entities/users/list) |
| `dateCreate` | datetime | да | Дата создания. В фильтре не принимается (`400 UNKNOWN_FILTER_FIELD`) |
| `timestampX` | datetime | да | Дата последнего изменения. В фильтре не принимается (`400 UNKNOWN_FILTER_FIELD`) |
| `previewText` | string | нет | Текст анонса |
| `previewTextType` | string | нет | Формат текста анонса: `text` или `html` |
| `detailText` | string | нет | Подробное описание |
| `detailTextType` | string | нет | Формат подробного описания: `text` или `html` |
| `previewPicture` | object | нет | Изображение анонса |
| `detailPicture` | object | нет | Детальное изображение |
| `priceType` | string | нет | Объявлено в справочнике, но в ответах списка и одной услуги не возвращается. Цены услуги задаются в [`POST /v1/catalog-prices`](/docs/entities/catalog-prices/create) |
| `propertyNNN` | productproperty | нет | Свойство каталога, где `NNN` — `id` свойства из [`GET /v1/catalog-product-properties`](/docs/entities/catalog-product-properties/list). Приходит только с `iblockId`, у множественных свойств — с `multiple: true`. Тип приходит от Битрикс24 как есть и в пятёрку типов статических полей не входит |

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

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

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

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

Ответ без `iblockId`: только статические поля и предупреждение `fields_partial`.

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": {
        "type": "number",
        "readonly": true,
        "label": "Идентификатор услуги",
        "description": "Уникальный идентификатор услуги каталога."
      },
      "iblockId": {
        "type": "number",
        "readonly": false,
        "createOnly": true,
        "label": "ID каталога",
        "description": "Каталог, которому принадлежит товар. Список: GET /v1/catalogs. Задаётся только при создании — смена через PATCH отклоняется, товар нельзя перенести между каталогами."
      },
      "type": {
        "type": "number",
        "readonly": true,
        "label": "Тип услуги",
        "description": "Тип услуги Битрикс24 (7); устанавливается Битрикс24 и доступен только для чтения."
      },
      "iblockSectionId": {
        "type": "number",
        "readonly": false,
        "nullable": true,
        "label": "ID раздела каталога",
        "description": "Основной раздел каталога у услуги; null, если товар не привязан к разделу. Список: GET /v1/catalog-sections."
      },
      "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" }
        ]
      }
    },
    "aggregatable": [
      "iblockSectionId"
    ],
    "batch": [
      "create",
      "update",
      "delete"
    ]
  },
  "meta": {
    "warnings": [
      {
        "code": "fields_partial",
        "message": "Dynamic field metadata from Bitrix24 was unavailable; the response carries static schema fields only and some labels may be missing. Retry to obtain the complete set."
      }
    ]
  }
}
```

Пример сокращён до шести полей — по одному на признаки `readonly`, `createOnly`, вычисляемый `type`, `nullable`, пару `writeOnly` + `notReturned` и словарь `enum`. Статический справочник содержит 28 полей. С `iblockId` успешный ответ содержит те же статические поля плюс свойства каталога `propertyNNN`, предупреждения `fields_partial` в нём нет. У свойства каталога `type` приходит от Битрикс24 как есть (`productproperty`), у множественного свойства есть ключ `multiple: true`, а когда Битрикс24 вернул словарь значений или значение по умолчанию — ключи `values`, `items` и `default`.

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

401 — не передан ключ:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}
```

## Ошибки

| 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).

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

**Для свойств каталога нужен `iblockId`.** Без номера каталога возвращаются статические поля и `fields_partial`. С `?iblockId=<ID каталога>` при успешном ответе Битрикс24 справочник включает свойства `propertyNNN`, а предупреждение отсутствует. Если Битрикс24 не вернул динамические поля, статический ответ с предупреждением сохраняется.

**Часть полей не приходит в списке по умолчанию.** Символьный код `code`, внешний код `xmlId`, сортировка `sort`, ставка `vatId`, тексты, картинки и свойства `propertyNNN` не возвращаются в ответе [`GET /v1/catalog-services`](./list.md) без явного `?select=`. Перечислите нужные имена в `select`, чтобы получить их в списке. В ответе одной услуги [`GET /v1/catalog-services/:id`](./get.md) они возвращаются всегда.

**Описания называют запись товаром.** В `description` части полей — например, `iblockId`, `active` и `createdBy` — услуга называется товаром. Речь идёт об услуге: `type` у каждой записи этого метода равен `7`.

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

- [Список услуг](/docs/entities/catalog-services/list)
- [Создать услугу](/docs/entities/catalog-services/create)
- [Получить услугу](/docs/entities/catalog-services/get)
- [Свойства товаров каталога](/docs/entities/catalog-product-properties)
- [Товары каталога](/docs/entities/catalog-products)
- [Справочник API](/docs/api-reference)