# Складские документы

Документы складского учёта: приход товара, оприходование, перемещение между складами, возврат и списание. Документ — это шапка с типом, валютой и ответственным. Товары и склады задаются его [позициями](./catalog-document-elements.md). Остатки на складах меняются, когда документ проводят, и возвращаются, когда проведение отменяют.

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

## Операции

- [Создать складской документ](./catalog-documents/create.md) — `POST /v1/catalog-documents`
- [Список складских документов](./catalog-documents/list.md) — `GET /v1/catalog-documents`
- [Получить складской документ](./catalog-documents/get.md) — `GET /v1/catalog-documents/:id`
- [Обновить складской документ](./catalog-documents/update.md) — `PATCH /v1/catalog-documents/:id`
- [Удалить складской документ](./catalog-documents/delete.md) — `DELETE /v1/catalog-documents/:id`
- [Поиск складских документов](./catalog-documents/search.md) — `POST /v1/catalog-documents/search`
- [Поля складского документа](./catalog-documents/fields.md) — `GET /v1/catalog-documents/fields`
- [Провести документ](./catalog-documents/conduct.md) — `POST /v1/catalog-documents/:id/conduct`
- [Отменить проведение](./catalog-documents/cancel.md) — `POST /v1/catalog-documents/:id/cancel`

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

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор документа (только чтение) |
| `docType` | string | Тип документа: `A` — приход, `S` — оприходование, `M` — перемещение, `R` — возврат, `D` — списание. Задаётся только при создании |
| `currency` | string | Валюта документа. Задаётся только при создании. Список валют — [`GET /v1/currencies`](/docs/entities/currencies/list) |
| `responsibleId` | number | Ответственный сотрудник — идентификатор из [`GET /v1/users`](/docs/entities/users/list) |
| `status` | string | Статус проведения: `Y` — проведён, `N` — не проведён. Только чтение, меняется действиями [провести](./catalog-documents/conduct.md) и [отменить проведение](./catalog-documents/cancel.md) |
| `title` | string | Название документа |
| `docNumber` | string | Номер документа |
| `dateDocument` | datetime | Дата документа |
| `dateCreate` | datetime | Дата создания (только чтение) |

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

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

1. **Тело запроса плоское.** При создании и обновлении передавайте поля прямо в корне JSON: `{"docType": "S", "currency": "RUB", "responsibleId": 1}`. Обёртка `fields` не нужна.
2. **Для создания обязательны три поля:** `docType`, `currency` и `responsibleId`. `docType` и `currency` после создания не меняются: запрос на обновление с ними возвращает `400 READONLY_FIELD`.
3. **Работают пять типов документа:** `A`, `S`, `M`, `R`, `D`. Другие коды типа отклоняются с `422 BITRIX_ERROR`.
4. **У документа два состояния.** Новый документ не проведён (`status: "N"`): документ можно менять и удалять, а его позиции — добавлять и править. После [проведения](./catalog-documents/conduct.md) (`status: "Y"`) изменение и удаление документа и его позиций отклоняются с `422 BITRIX_ERROR`. Чтобы снова править документ, [отмените проведение](./catalog-documents/cancel.md).
5. **Склады проверяются при проведении.** Позиция с неподходящими для типа документа складами создаётся без ошибки, а проведение документа отклоняется с `422 BITRIX_ERROR`. Какие склады нужны каждому типу — [Позиции складских документов](./catalog-document-elements.md).
6. **Приход (`A`) проводится только с указанным поставщиком.** Среди полей документа нет поставщика, поэтому проведение прихода, созданного через API, отклоняется с `422 BITRIX_ERROR` «Не указан поставщик». Оприходование (`S`) поставщика не требует.
7. **Удаление документа удаляет его позиции.** После `DELETE /v1/catalog-documents/:id` позиций этого документа больше нет.
8. **Даты приходят в ISO 8601 по UTC:** `2026-10-12T13:20:16.000Z`.

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

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

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

Оприходование товара на склад:

1. Выбрать склад: [`GET /v1/warehouses`](/docs/entities/warehouses/list) — взять `id` склада.
2. Создать документ оприходования: [`POST /v1/catalog-documents`](./catalog-documents/create.md) с `docType: "S"`, `currency` и `responsibleId`.
3. Добавить товары: [`POST /v1/catalog-document-elements`](/docs/entities/catalog-document-elements/create) — по одной позиции на товар с `docId`, `elementId`, `amount` и `storeTo`.
4. Провести документ: [`POST /v1/catalog-documents/:id/conduct`](./catalog-documents/conduct.md).
5. Проверить остаток: [`GET /v1/warehouses/:id/stock`](/docs/entities/warehouses/stock).

## Лимиты

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

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

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