# Позиции корзины

Управление товарными позициями в заказах: создание, получение, обновление, удаление, поиск, агрегация. Позиция корзины — отдельная сущность, привязанная к заказу по полю `orderId`. У одного заказа может быть несколько позиций — по одной на каждый купленный товар.

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

## Операции

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

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

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор позиции (только чтение) |
| `orderId` | number | Обязателен при создании. Идентификатор заказа. Источник: [`GET /v1/orders`](./orders/list.md) |
| `productId` | number | Обязателен при создании. Идентификатор товара в каталоге. `0` — виртуальная позиция без привязки к каталогу. Источник: [`GET /v1/catalog-products`](/docs/entities/catalog-products) |
| `name` | string | Название позиции. Для каталожного товара заполняется из карточки |
| `price` | number | Цена за единицу |
| `basePrice` | number | Базовая цена до скидки |
| `discountPrice` | number | Размер скидки за единицу |
| `quantity` | number | Обязательно при создании. Количество |
| `currency` | string | Обязательна при создании. Валюта позиции. Список: [`GET /v1/currencies`](/docs/entities/currencies) |
| `vatRate` | number | Ставка НДС в долях единицы (`0.20` = 20%) |
| `vatIncluded` | boolean | Включён ли НДС в цену |
| `weight` | number | Вес в граммах |
| `dimensions` | string | Габариты в формате сериализации PHP |
| `measureCode` | number | Код единицы измерения (`796` = шт, `163` = г, `006` = м и др.) |
| `measureName` | string | Название единицы измерения |
| `xmlId` | string | Внешний идентификатор позиции |

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

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

1. **Тело запроса плоское.** При создании и обновлении передавайте поля прямо в корне JSON: `{"orderId": 33, "productId": 119, ...}`. Обёртка `fields` не нужна.
2. **Обязательные поля при создании.** Для добавления позиции нужны `orderId`, `productId`, `currency` и `quantity`. Поле `orderId` ссылается на существующий заказ — сначала вызовите [`POST /v1/orders`](./orders/create.md). Поле `productId` привязывает позицию к товару каталога. Значение `productId: 0` создаёт виртуальную позицию без привязки к каталогу — для неё `name` и `price` задаются вручную.
3. **`vatRate` хранится в долях единицы.** Для НДС 20% передавайте `0.20`, не `20`. Для 10% — `0.10`. Для без НДС — `0` или не передавать.
4. **Цены передавайте согласованно.** `price` — итоговая цена за единицу с учётом скидки, `basePrice` — до скидки, `discountPrice` — размер скидки. Битрикс24 не пересчитывает эти поля между собой автоматически. Передайте `customPrice: true`, чтобы цена позиции не обновлялась при изменении цены товара в каталоге.

## Связанные сущности

| Сущность | Эндпоинт | Назначение |
|----------|----------|-----------|
| Заказы | [`GET /v1/orders/:id`](./orders/get.md) | Родительский заказ — `orderId` указывается при создании позиции. |
| Товары каталога | [`GET /v1/catalog-products`](/docs/entities/catalog-products) | Источник `productId` для привязки позиции к товару. |
| Оплаты | [`GET /v1/payments?filter[orderId]=:id`](./payments.md) | Платежи по тому же заказу. |

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

Добавление товаров в заказ из внешней системы:

1. Создать заказ: [`POST /v1/orders`](./orders/create.md) — получить `orderId`.
2. Найти товары в каталоге: [`GET /v1/catalog-products`](/docs/entities/catalog-products) — получить `productId` для каждой позиции.
3. Добавить позиции: цикл [`POST /v1/basket-items`](./basket-items/create.md) с `orderId`, `productId`, `quantity`, `price`, `currency`, `vatRate`.
4. Зарегистрировать оплату: [`POST /v1/payments`](./payments/create.md).

## Лимиты

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

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

- [Поля позиции](./basket-items/fields.md)
- [Заказы](./orders.md)
- [Оплаты](./payments.md)
- [Товары каталога](/docs/entities/catalog-products)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Справочник API](/docs/api-reference)