# Услуги каталога

Услуги товарного каталога: список, получение, создание, изменение и удаление. Услуга — запись каталога с типом `7` для работ и сервиса, например монтажа или доставки. Складских полей — остатка, веса и закупочной цены — у услуги нет, цены продажи задаются в [Ценах каталога](/docs/entities/catalog-prices).

Битрикс24 API: `catalog.product.service.*`
Скоуп: `catalog`

## Операции

- [Создать услугу](./catalog-services/create.md) — `POST /v1/catalog-services`
- [Список услуг](./catalog-services/list.md) — `GET /v1/catalog-services`
- [Получить услугу](./catalog-services/get.md) — `GET /v1/catalog-services/:id`
- [Изменить услугу](./catalog-services/update.md) — `PATCH /v1/catalog-services/:id`
- [Удалить услугу](./catalog-services/delete.md) — `DELETE /v1/catalog-services/:id`
- [Поиск услуг](./catalog-services/search.md) — `POST /v1/catalog-services/search`
- [Поля услуги](./catalog-services/fields.md) — `GET /v1/catalog-services/fields`
- [Агрегация услуг](./catalog-services/aggregate.md) — `POST /v1/catalog-services/aggregate`

## Ключевые поля

| Поле | Описание |
|------|---------|
| `name` | Название услуги |
| `iblockId` | ID товарного каталога — каталога, у которого не заполнен `productIblockId`. Обязателен при создании и в фильтре списка, поиска и агрегации. Список: [`GET /v1/catalogs`](/docs/entities/catalogs/list) |
| `iblockSectionId` | ID раздела каталога. Список: [`GET /v1/catalog-sections`](/docs/entities/catalog-sections/list) |
| `type` | Тип записи, у услуги всегда `7`. Заполняется Битрикс24 |
| `active` | Активна ли услуга |
| `available` | Доступна ли услуга к покупке. Если поле не передано при создании, услуга создаётся с `false` |
| `measure` | ID единицы измерения. Список: [`GET /v1/catalog-measures`](/docs/entities/catalog-measures/list) |
| `vatIncluded` | НДС включён в цену |

Полный список полей — [`GET /v1/catalog-services/fields`](./catalog-services/fields.md).

## Что нужно знать перед работой

1. **Услуги хранятся в товарном каталоге.** В [`GET /v1/catalogs`](/docs/entities/catalogs/list) это запись без `productIblockId`. Её `id` передаётся в `iblockId` при создании услуги и в фильтре списка, поиска и агрегации. С `iblockId` каталога вариаций список и создание отвечают `422 BITRIX_ERROR` с текстом `productType is not allowed for this catalog`.
2. **Список, поиск и агрегация требуют фильтр по каталогу.** Без `filter[iblockId]` запрос отклоняется с `400 MISSING_REQUIRED_FILTER` до обращения к Битрикс24.
3. **В выдачу попадают только услуги.** Каждая запись приходит с `type: 7`, обычные товары каталога в список не входят. Фильтр по `type` выборку не меняет.
4. **Выборка полей строгая.** Если в списке или поиске передан `select`, в нём обязательны `iblockId` и `id`, а неизвестное имя отклоняется с `400 UNKNOWN_SELECT_FIELD`. Без `select` список возвращает сокращённый набор полей, а одна запись по `id` — полный, вместе со свойствами каталога вида `propertyNNN`.
5. **Минимум для создания — `name` и `iblockId`.** Без `name` запрос отклоняется с `422 BITRIX_ERROR` и текстом `Required fields: name`, без `iblockId` — с текстом `iblock is not catalog`.
6. **Изменение и удаление проверяют, что по `id` лежит услуга.** С `id` обычного товара `PATCH` и `DELETE` отвечают `404 ENTITY_NOT_FOUND`, товар остаётся без изменений.
7. **Свойства каталога в справочнике полей требуют `iblockId`.** [`GET /v1/catalog-services/fields?iblockId=25`](./catalog-services/fields.md) при успешном ответе Битрикс24 возвращает 28 статических полей вместе со свойствами каталога `propertyNNN`, предупреждения `fields_partial` в нём нет. Без параметра приходят только 28 статических полей и предупреждение `fields_partial`. Значения свойств приходят в ответе одной услуги, их названия и типы доступны также в [`GET /v1/catalog-product-properties`](/docs/entities/catalog-product-properties/list).

## Типичный сценарий

1. Найти товарный каталог и его `id`: [`GET /v1/catalogs`](/docs/entities/catalogs/list) — запись без `productIblockId`.
2. Выбрать раздел для услуги: [`GET /v1/catalog-sections?filter[iblockId]=25`](/docs/entities/catalog-sections/list).
3. Создать услугу: [`POST /v1/catalog-services`](./catalog-services/create.md).
4. Задать цену услуги — `id` услуги передаётся в `productId`: [`POST /v1/catalog-prices`](/docs/entities/catalog-prices/create).
5. Посмотреть услуги раздела: [`GET /v1/catalog-services?filter[iblockId]=25&filter[iblockSectionId]=281`](./catalog-services/list.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Авто-пагинация | включается при `limit > 50` |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Товары каталога](/docs/entities/catalog-products)
- [Цены каталога](/docs/entities/catalog-prices)
- [Каталоги](/docs/entities/catalogs)
- [Разделы каталога](/docs/entities/catalog-sections)
- [Единицы измерения](/docs/entities/catalog-measures)
- [Свойства товаров каталога](/docs/entities/catalog-product-properties)
- [Синтаксис фильтрации](/docs/filtering)
- [Справочник API](/docs/api-reference)