# Позиции складских документов

Товарные строки [складских документов](./catalog-documents.md): какой товар, в каком количестве, по какой закупочной цене и между какими складами движется. У одного документа может быть несколько позиций. Позиции можно менять, пока документ не проведён.

Битрикс24 API: `catalog.document.element.*`
Скоуп: `catalog`

## Операции

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

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

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор позиции (только чтение) |
| `docId` | number | Документ — идентификатор из [`GET /v1/catalog-documents`](/docs/entities/catalog-documents/list). Задаётся только при создании |
| `elementId` | number | Товар — идентификатор из [`GET /v1/catalog-products`](/docs/entities/catalog-products/list). Задаётся только при создании |
| `amount` | number | Количество товара |
| `purchasingPrice` | number | Закупочная цена за единицу |
| `storeFrom` | number | Склад отправления — идентификатор из [`GET /v1/warehouses`](/docs/entities/warehouses/list) |
| `storeTo` | number | Склад получения — идентификатор из [`GET /v1/warehouses`](/docs/entities/warehouses/list) |

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

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

1. **Тело запроса плоское.** При создании и обновлении передавайте поля прямо в корне JSON: `{"docId": 42, "elementId": 6595, "amount": 3}`. Обёртка `fields` не нужна.
2. **Для создания обязательны `docId` и `elementId`.** После создания оба поля не меняются: запрос на обновление с ними возвращает `400 READONLY_FIELD`. Чтобы перенести товар в другой документ или заменить товар, удалите позицию и создайте новую.
3. **Склады зависят от типа документа.** Приходу (`A`), оприходованию (`S`) и возврату (`R`) нужен склад получения `storeTo`, списанию (`D`) — склад отправления `storeFrom`, перемещению (`M`) — оба. Позиция с неподходящими складами создаётся без ошибки, а проведение документа отклоняется с `422 BITRIX_ERROR` и названием товара, у которого не указан склад.
4. **Позиции проведённого документа не меняются.** Добавление позиции в проведённый документ, обновление и удаление его позиций отклоняются с `422 BITRIX_ERROR`. Сначала [отмените проведение документа](/docs/entities/catalog-documents/cancel).
5. **Позиции удаляются вместе с документом.** Удалять их отдельно перед [удалением документа](/docs/entities/catalog-documents/delete) не нужно. После удаления запрос позиции по её `id` возвращает `404 ENTITY_NOT_FOUND`.

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

| Сущность | Эндпоинт | Назначение |
|----------|----------|-----------|
| Складские документы | [`GET /v1/catalog-documents`](/docs/entities/catalog-documents/list) | Документ, к которому относится позиция, — значение `docId`. Тип документа определяет, какие склады нужны позиции. |
| Товары каталога | [`GET /v1/catalog-products`](/docs/entities/catalog-products/list) | Товары для поля `elementId`. |
| Склады | [`GET /v1/warehouses`](/docs/entities/warehouses/list) | Склады для полей `storeFrom` и `storeTo`. Остатки после проведения — [`GET /v1/warehouses/:id/stock`](/docs/entities/warehouses/stock). |

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

Наполнение документа товарами перед проведением:

1. Найти документ: [`GET /v1/catalog-documents`](/docs/entities/catalog-documents/list) — взять `id` и `docType`.
2. Посмотреть его позиции: [`GET /v1/catalog-document-elements?filter[docId]=:id`](./catalog-document-elements/list.md).
3. Добавить товар: [`POST /v1/catalog-document-elements`](./catalog-document-elements/create.md) с `docId`, `elementId`, `amount` и складами по типу документа.
4. Исправить количество или цену: [`PATCH /v1/catalog-document-elements/:id`](./catalog-document-elements/update.md).
5. Провести документ: [`POST /v1/catalog-documents/:id/conduct`](/docs/entities/catalog-documents/conduct).

## Лимиты

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

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

- [Складские документы](./catalog-documents.md)
- [Склады](./warehouses.md)
- [Товары каталога](./catalog-products.md)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Справочник API](/docs/api-reference)