# Свойства позиций корзины

Свойства конкретной позиции корзины: название, значение, символьный код и порядок сортировки.

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

## Операции

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

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

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | ID свойства. Список: [`GET /v1/basket-item-properties`](./basket-item-properties/list.md). Только чтение |
| `basketId` | number | ID позиции корзины из [`GET /v1/basket-items`](/docs/entities/basket-items/list). Обязателен при создании, не изменяется через `PATCH` |
| `name` | string | Название свойства. Обязательно при создании |
| `value` | string \| null | Значение свойства. Обязательно при создании |
| `code` | string \| null | Символьный код свойства. Обязателен при создании |
| `sort` | number | Порядок сортировки свойства внутри позиции |
| `xmlId` | string \| null | Внешний идентификатор |

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

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

1. **Чтение в карточке позиции и запись разделены.** [`GET /v1/basket-items/:id`](/docs/entities/basket-items/get) возвращает свойства в поле `properties`, доступном только для чтения. Для создания, изменения и удаления используйте методы этого раздела.
2. **Свойства заказа выбираются через позиции корзины.** Получите ID позиций через [`GET /v1/basket-items`](/docs/entities/basket-items/list) с фильтром по `orderId`. Источник `orderId` — [`GET /v1/orders`](/docs/entities/orders/list). Затем передайте ID позиций в фильтре `basketId` [списка](./basket-item-properties/list.md) или [поиска](./basket-item-properties/search.md).
3. **Частичное изменение сохраняет неуказанные поля.** Если в `PATCH` пропущены `name`, `code` или `value`, Вайбкод перечитывает свойство и подставляет сохранённые значения. В пакетном обновлении передавайте все три поля явно для каждого свойства. Формат — [Пакетные вызовы](/docs/batch).
4. **Создание и удаление свойства сохраняют заказ.** У заказа, которому принадлежит позиция корзины, обновляются `dateUpdate` и `version`.

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

1. Выбрать позицию корзины и получить её `id`: [`GET /v1/basket-items`](/docs/entities/basket-items/list).
2. Проверить её свойства фильтром по `basketId`: [`GET /v1/basket-item-properties`](./basket-item-properties/list.md).
3. Создать свойство с `basketId`, `name`, `value` и `code`: [`POST /v1/basket-item-properties`](./basket-item-properties/create.md).
4. Прочитать свойство по полученному `id`: [`GET /v1/basket-item-properties/:id`](./basket-item-properties/get.md).
5. Изменить значение: [`PATCH /v1/basket-item-properties/:id`](./basket-item-properties/update.md).
6. Когда свойство больше не нужно, удалить его: [`DELETE /v1/basket-item-properties/:id`](./basket-item-properties/delete.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Записей на запрос списка или поиска | `limit` от 1 до 5000, по умолчанию 50. Следующие записи запрашиваются через `offset`. См. [Список свойств позиций корзины](./basket-item-properties/list.md) и [Поиск свойств позиций корзины](./basket-item-properties/search.md) |
| Автоматическая пагинация | При `limit > 50` Вайбкод читает страницы Битрикс24 по 50 записей и объединяет их в один ответ. См. [Список](./basket-item-properties/list.md) |
| Пакетные вызовы | `POST /v1/batch` и `POST /v1/basket-item-properties/batch`. По умолчанию до 500 элементов для записи и до 50 вызовов для чтения. Настройки платформы могут менять лимиты. Формат — [Пакетные вызовы](/docs/batch) |
| Частота запросов | Общий лимит API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Позиции корзины](/docs/entities/basket-items)
- [Заказы](/docs/entities/orders)
- [Синтаксис фильтрации](/docs/filtering)
- [API сущностей](/docs/entity-api)
- [Пакетные вызовы](/docs/batch)