# Воронки

Универсальное управление воронками CRM для любого типа сущности: сделок, смарт-процессов и других. Каждая воронка содержит свой набор стадий. В отличие от [воронок сделок](/docs/entities/deal-categories), этот эндпоинт работает для всех типов CRM через единый путь.

Битрикс24 API: `crm.category.*`
Скоуп: `crm`

Путь содержит динамический параметр `:entityTypeId` — ID типа CRM-сущности. Для сделок это `2`, для счетов — `31`, для смарт-процессов — значение из `GET /v1/smart-processes`. Основная воронка сделок доступна здесь по id `0`.

## Операции

- [Создать воронку](./categories/create.md) — `POST /v1/categories/:entityTypeId`
- [Список воронок](./categories/list.md) — `GET /v1/categories/:entityTypeId`
- [Поиск воронок](./categories/search.md) — `POST /v1/categories/:entityTypeId/search`
- [Получить воронку](./categories/get.md) — `GET /v1/categories/:entityTypeId/:id`
- [Обновить воронку](./categories/update.md) — `PATCH /v1/categories/:entityTypeId/:id`
- [Удалить воронку](./categories/delete.md) — `DELETE /v1/categories/:entityTypeId/:id`
- [Поля воронки](./categories/fields.md) — `GET /v1/categories/:entityTypeId/fields`

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

| Поле | Описание |
|------|---------|
| `id` | ID воронки. Для сделок основная воронка имеет id `0` |
| `entityTypeId` | ID типа CRM-сущности, повторяет параметр пути |
| `name` | Название воронки. Обязательно при создании |
| `sort` | Порядок сортировки |
| `isDefault` | Признак основной воронки типа |

Полный список полей — [`GET /v1/categories/:entityTypeId/fields`](./categories/fields.md). Стадии воронки берутся отдельно: `GET /v1/statuses?filter[entityId]=DEAL_STAGE_{id}`.

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

1. Воронка задаёт свой набор стадий: они запрашиваются отдельно через `GET /v1/statuses`. Сама воронка хранит только название и сортировку.
2. Для создания достаточно одного поля `name`. Без него ответ — `422` с сообщением `Field 'NAME' is required.`
3. Поддерживаются сделки `2`, счета `31` и смарт-процессы. Предложения `7` воронок не имеют — запрос вернёт `422` с сообщением о неподдерживаемой сущности. Резервные id `2` и `31` здесь рабочие, в отличие от `/v1/items`.
4. **Поля `code` и `isDefault` — только чтение.** Передача любого из них в теле при создании или обновлении возвращает `400` с кодом `READONLY_FIELD`, сообщение называет конкретное поле. Записываются `name` и `sort`. Основная воронка типа назначается в интерфейсе Битрикс24.
5. **Отбор воронок задаётся не запросом.** `select`, `limit` и `offset` работают: `select` сужает набор полей, `limit` и `offset` режут выдачу постранично. А вот `filter` и `order` принимаются без ошибки, но не действуют — состав и порядок воронок типа всегда одинаковы, сортировка идёт по полю `sort`. Нужен отбор по названию — отфильтруйте полученный список на стороне клиента.

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

1. Определить тип CRM-сущности: для сделок `entityTypeId` равен `2`, для смарт-процесса — значение из [`GET /v1/smart-processes`](/docs/entities/smart-processes/list).
2. Посмотреть существующие воронки типа: [`GET /v1/categories/2`](./categories/list.md).
3. Создать новую или обновить существующую: [`POST /v1/categories/2`](./categories/create.md) / [`PATCH /v1/categories/2/:id`](./categories/update.md).
4. Запросить стадии нужной воронки: `GET /v1/statuses?filter[entityId]=DEAL_STAGE_{id}`.

## Лимиты

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

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

- [Воронки сделок](/docs/entities/deal-categories)
- [Стадии и статусы](/docs/entities/statuses)
- [Типы смарт-процессов](/docs/entities/smart-processes)
- [Справочник API](/docs/api-reference)