# Смарт-процессы (Items)

Управление элементами смарт-процессов CRM: создание, получение, обновление, удаление, фильтрация.

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

Путь содержит динамический параметр `:entityTypeId` — ID типа смарт-процесса. Узнать доступные типы: `GET /v1/smart-processes`.

## Операции

- [Создать элемент](./items/create.md) — `POST /v1/items/:entityTypeId`
- [Список элементов](./items/list.md) — `GET /v1/items/:entityTypeId`
- [Получить элемент](./items/get.md) — `GET /v1/items/:entityTypeId/:id`
- [Обновить элемент](./items/update.md) — `PATCH /v1/items/:entityTypeId/:id`
- [Удалить элемент](./items/delete.md) — `DELETE /v1/items/:entityTypeId/:id`
- [Поиск элементов](./items/search.md) — `POST /v1/items/:entityTypeId/search`
- [Поля элемента](./items/fields.md) — `GET /v1/items/:entityTypeId/fields`
- [Агрегация элементов](./items/aggregate.md) — `POST /v1/items/:entityTypeId/aggregate`
- [Получить товары](./items/products-get.md) — `GET /v1/items/:entityTypeId/:id/products`
- [Установить товары](./items/products-set.md) — `PUT /v1/items/:entityTypeId/:id/products`
- [Добавить товар](./items/products-add.md) — `POST /v1/items/:entityTypeId/:id/products`
- [Удалить товар](./items/products-delete.md) — `DELETE /v1/items/:entityTypeId/:id/products/:rowId`
- [Получить товар](./items/products-get-single.md) — `GET /v1/items/:entityTypeId/:id/products/:rowId`
- [Обновить товар](./items/products-update.md) — `PATCH /v1/items/:entityTypeId/:id/products/:rowId`
- [Поля товаров](./items/products-fields.md) — `GET /v1/items/:entityTypeId/:id/products/fields`

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

| Поле | Описание |
|------|---------|
| `title` | Название элемента |
| `stageId` | Стадия. Формат `DT{typeId}_{catId}:{stage}`. Список: `GET /v1/statuses?filter[entityId]=DYNAMIC_{entityTypeId}_STAGE_{categoryId}` |
| `categoryId` | ID воронки. Список: `GET /v1/categories/:entityTypeId` |
| `opportunity` | Сумма |
| `currencyId` | Валюта. Список: `GET /v1/currencies` |
| `assignedById` | Ответственный. Список: `GET /v1/users` |
| `companyId` / `contactId` | Привязки к компании и контакту. Списки: `GET /v1/companies`, `GET /v1/contacts` |

Полный список полей — [`GET /v1/items/:entityTypeId/fields`](./items/fields.md).

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

1. `entityTypeId` в пути — ID типа смарт-процесса из [`GET /v1/smart-processes`](/docs/entities/smart-processes). Значения `1`, `2`, `3`, `4`, `7`, `31` зарезервированы за специализированными API (`/v1/leads`, `/v1/deals`, `/v1/contacts`, `/v1/companies`, `/v1/quotes`, `/v1/invoices`) — обращение к ним через `/v1/items` возвращает `400 INVALID_DYNAMIC_PARAM`.
2. Минимум для создания — `title`. Остальные обязательные поля зависят от настроек типа.
3. Имена пользовательских полей используют внутренний номер типа — `ufCrm<typeId>_*`, который не равен `entityTypeId`. Точные имена приходят в [`GET /v1/items/:entityTypeId/fields`](./items/fields.md).
4. Поля-даты `begindate` и `closedate` хранятся без времени — переданное время отбрасывается.
5. Списочные ответы кладут пагинацию в `meta` (`meta.total`, `meta.hasMore`), не на верхний уровень.

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

1. Найти тип смарт-процесса: [`GET /v1/smart-processes`](/docs/entities/smart-processes) — взять `entityTypeId`.
2. Посмотреть поля типа: [`GET /v1/items/:entityTypeId/fields`](./items/fields.md).
3. Создать элемент: [`POST /v1/items/:entityTypeId`](./items/create.md).
4. Найти и отфильтровать: [`GET /v1/items/:entityTypeId`](./items/list.md) или [`POST /v1/items/:entityTypeId/search`](./items/search.md).
5. При необходимости — добавить товарную позицию: [`POST /v1/items/:entityTypeId/:id/products`](./items/products-add.md).

## Лимиты

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

## Пользовательские поля

Управление пользовательскими полями элементов смарт-процесса — отдельный раздел: [Поля смарт-процессов](/docs/userfields/smart-processes) (`/v1/items/:entityTypeId/userfields*`).

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

- [Типы смарт-процессов](/docs/entities/smart-processes)
- [Поля смарт-процессов](/docs/userfields/smart-processes)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Справочник API](/docs/api-reference)
- [Импорт записей](../import.md) — `POST /v1/items/:entityTypeId/import`