# Позиции отгрузок

Состав отгрузки заказа интернет-магазина: какая позиция корзины и в каком количестве входит в отгрузку.

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

## Операции

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

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

| Поле | Тип | Описание |
|------|-----|---------|
| `orderDeliveryId` | number | ID отгрузки. Список: [`GET /v1/shipments`](/docs/entities/shipments/list). Задаётся только при создании |
| `basketId` | number | ID позиции корзины того же заказа. Список: [`GET /v1/basket-items`](/docs/entities/basket-items/list). Задаётся только при создании |
| `quantity` | number | Количество товара в отгрузке, допускается дробное |
| `reservedQuantity` | number | Зарезервированное количество, только для чтения |
| `xmlId` | string | Внешний код позиции |

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

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

1. **Нераспределённый остаток корзины лежит в системной отгрузке.** У каждой позиции корзины есть строка в системной отгрузке заказа. Создание позиции в обычной отгрузке уменьшает количество в системной строке, удаление возвращает его обратно. Количество сверх остатка отклоняется с `422 BITRIX_ERROR`. Системная отгрузка не отдаётся через [`GET /v1/shipments/:id`](/docs/entities/shipments/get), а её позиции видны в списке позиций. Напрямую позицию системной отгрузки изменить нельзя: остаток меняется только через позиции обычных отгрузок.
2. **Отгрузка и корзина задаются только при создании.** Для создания нужны `orderDeliveryId`, `basketId` и `quantity`, отгрузка и позиция корзины относятся к одному заказу. Одна позиция корзины входит в отгрузку одной строкой: повторная пара `basketId` и `orderDeliveryId` отклоняется. Перенести позицию в другую отгрузку можно только удалением и созданием заново.
3. **`quantity` передаётся в каждом изменении.** [`PATCH /v1/shipment-items/:id`](./shipment-items/update.md) без `quantity` отклоняется с `422 BITRIX_ERROR`, даже если меняется только `xmlId`.
4. **Не каждая строка списка открывается по `id`.** Позиции системной отгрузки и позиции отгрузок, которых уже нет, возвращаются [`GET /v1/shipment-items`](./shipment-items/list.md), но [`GET /v1/shipment-items/:id`](./shipment-items/get.md) отвечает на них `404 ENTITY_NOT_FOUND`. Чтобы получить состав конкретной отгрузки, фильтруйте по `filter[orderDeliveryId]`.

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

1. Найти заказ: [`GET /v1/orders`](/docs/entities/orders/list).
2. Найти позиции корзины заказа: [`GET /v1/basket-items?filter[orderId]=1027`](/docs/entities/basket-items/list).
3. Создать отгрузку или выбрать существующую: [`POST /v1/shipments`](/docs/entities/shipments/create).
4. Добавить позицию корзины в отгрузку: [`POST /v1/shipment-items`](./shipment-items/create.md) с `orderDeliveryId`, `basketId` и `quantity`.
5. Проверить состав отгрузки: [`GET /v1/shipment-items?filter[orderDeliveryId]=1207`](./shipment-items/list.md).
6. Изменить количество: [`PATCH /v1/shipment-items/:id`](./shipment-items/update.md) или убрать позицию: [`DELETE /v1/shipment-items/:id`](./shipment-items/delete.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Записей на запрос списка | до 5000 (`limit`), по умолчанию 50 |
| Агрегация | функции `count`, `sum`, `avg`, `min`, `max` в [`POST /v1/shipment-items/aggregate`](./shipment-items/aggregate.md) |
| Пакетные операции | создание, изменение и удаление в [`POST /v1/shipment-items/batch`](./shipment-items/batch.md) |
| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Отгрузки](/docs/entities/shipments)
- [Позиции корзины](/docs/entities/basket-items)
- [Заказы](/docs/entities/orders)
- [Доставки CRM](/docs/entities/crm-deliveries)
- [Справочник сущностей](/docs/entity-api)