## Создать складской документ `POST /v1/catalog-documents` Создаёт складской документ — шапку прихода, оприходования, перемещения, возврата или списания. Поля передаются плоско в корне JSON, без обёртки `fields`. ## Поля запроса (body) | Поле | Тип | Обяз. | Описание | |------|-----|:-----:|---------| | `docType` | string | да | Тип документа: `A` — приход, `S` — оприходование, `M` — перемещение, `R` — возврат, `D` — списание. После создания не меняется. Подробнее о типах — [Складские документы](/docs/entities/catalog-documents) | | `currency` | string | да | Валюта документа. После создания не меняется. Список: [`GET /v1/currencies`](/docs/entities/currencies/list) | | `responsibleId` | number | да | Ответственный сотрудник. Список: [`GET /v1/users`](/docs/entities/users/list) | | `title` | string | нет | Название документа | | `docNumber` | string | нет | Номер документа | | `commentary` | string | нет | Комментарий | | `dateDocument` | datetime | нет | Дата документа | | `total` | number | нет | Сумма документа. Из позиций не рассчитывается: после проведения поле хранит переданное значение или `null` | | `siteId` | string | нет | Идентификатор сайта портала. Если не передать при создании, подставляется `s1` | | `createdBy` | number | нет | Сотрудник, создавший документ. После создания не меняется. Список: [`GET /v1/users`](/docs/entities/users/list) | | `modifiedBy` | number | нет | Сотрудник, последним изменивший документ. Список: [`GET /v1/users`](/docs/entities/users/list) | | `statusBy` | number | нет | Сотрудник, последним изменивший статус проведения. Список: [`GET /v1/users`](/docs/entities/users/list) | | `dateModify` | datetime | нет | Дата последнего изменения | Полный список полей — [`GET /v1/catalog-documents/fields`](/docs/entities/catalog-documents/fields). ## Примеры ### curl — личный ключ ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-documents" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "docType": "S", "currency": "RUB", "responsibleId": 1, "title": "Корректировка остатков — проверка документации" }' ``` ### curl — OAuth-приложение ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-documents" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "docType": "S", "currency": "RUB", "responsibleId": 1, "title": "Корректировка остатков — проверка документации" }' ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-documents', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ docType: 'S', currency: 'RUB', responsibleId: 1, title: 'Корректировка остатков — проверка документации', }), }) const { success, data } = await res.json() console.log('Document ID:', data.id) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-documents', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ docType: 'S', currency: 'RUB', responsibleId: 1, title: 'Корректировка остатков — проверка документации', }), }) const { success, data } = await res.json() ``` ## Поля ответа HTTP-статус `201 Created`. | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | `true` при успешном создании | | `data` | object | Созданный документ. Все поля — [Поля складского документа](/docs/entities/catalog-documents/fields) | | `data.id` | number | Идентификатор созданного документа | | `data.status` | string | Статус проведения. У нового документа всегда `N` — не проведён | | `data.dateCreate` | datetime | Дата создания, ISO 8601 по UTC | | `data.dateStatus` | datetime | Дата последней смены статуса. У нового документа совпадает с `dateCreate` | | `data.dateModify` | datetime | Дата последнего изменения | | `meta.warnings` | array | Приходит, только если в теле есть поле, которого нет среди полей документа. Элемент — `code: "UNRECOGNIZED_WRITE_FIELD"`, `field` с именем поля и `message`. Объект `fields` на маршруте, который сам оборачивает карту полей и где схема не объявляет `fields`, отклоняется с `400 NESTED_FIELDS_ENVELOPE`; передавайте поля плоско в корне JSON. | ## Пример ответа ```json { "success": true, "data": { "commentary": null, "createdBy": 1, "currency": "RUB", "dateCreate": "2026-10-12T13:20:16.000Z", "dateDocument": null, "dateModify": "2026-10-12T13:20:16.000Z", "dateStatus": "2026-10-12T13:20:16.000Z", "docNumber": null, "docType": "S", "id": 299, "modifiedBy": 1, "responsibleId": 1, "siteId": "s1", "status": "N", "statusBy": null, "title": "Корректировка остатков — проверка документации", "total": null } } ``` ## Пример ответа при ошибке 400 — не передано обязательное поле: ```json { "success": false, "error": { "code": "MISSING_REQUIRED_FIELDS", "message": "Body field \"currency\" is required to create catalogDocument." } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `MISSING_REQUIRED_FIELDS` | Не передано одно из полей `docType`, `currency`, `responsibleId`. Имя поля — в `error.message` | | 400 | `READONLY_FIELD` | Передано поле, которое задаёт система: `id`, `status`, `dateStatus`, `dateCreate` | | 400 | `INVALID_PARAMS` | Значение поля не подходит по типу: нечисловая строка в числовом поле, например `"responsibleId": "abc"`, либо объект или массив вместо числа или строки. Имя поля — в `error.message` | | 422 | `BITRIX_ERROR` | В `docType` передан код, которого нет среди пяти типов. Сообщение `DOC_TYPE isn't available` | | 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ работает в режиме только для чтения | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `catalog` | | 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов | | 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | | 401 | `INVALID_API_KEY` | Переданный API-ключ не найден | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Смотрите также - [Складские документы](/docs/entities/catalog-documents) - [Обновить складской документ](/docs/entities/catalog-documents/update) - [Провести документ](/docs/entities/catalog-documents/conduct) - [Поля складского документа](/docs/entities/catalog-documents/fields) - [Создать позицию складского документа](/docs/entities/catalog-document-elements/create) - [Batch](/docs/batch)