Для AI-агентов: markdown этой страницы — /docs-content/entities/catalog-documents.md индекс документации — /llms.txt

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

Документы складского учёта: приход товара, оприходование, перемещение между складами, возврат и списание. Документ — это шапка с типом, валютой и ответственным. Товары и склады задаются его позициями. Остатки на складах меняются, когда документ проводят, и возвращаются, когда проведение отменяют.

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

Создать складской документ

POST /v1/catalog-documents

Создаёт складской документ — шапку прихода, оприходования, перемещения, возврата или списания.

Поля передаются плоско в корне JSON, без обёртки fields.

Поля запроса (body)

Поле Тип Обяз. Описание
docType string да Тип документа: A — приход, S — оприходование, M — перемещение, R — возврат, D — списание. После создания не меняется. Подробнее о типах — Складские документы
currency string да Валюта документа. После создания не меняется. Список: GET /v1/currencies
responsibleId number да Ответственный сотрудник. Список: GET /v1/users
title string нет Название документа
docNumber string нет Номер документа
commentary string нет Комментарий
dateDocument datetime нет Дата документа
total number нет Сумма документа. Из позиций не рассчитывается: после проведения поле хранит переданное значение или null
siteId string нет Идентификатор сайта портала. Если не передать при создании, подставляется s1
createdBy number нет Сотрудник, создавший документ. После создания не меняется. Список: GET /v1/users
modifiedBy number нет Сотрудник, последним изменивший документ. Список: GET /v1/users
statusBy number нет Сотрудник, последним изменивший статус проведения. Список: GET /v1/users
dateModify datetime нет Дата последнего изменения

Полный список полей — GET /v1/catalog-documents/fields.

Примеры

curl — личный ключ

Terminal 
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-приложение

Terminal 
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 Созданный документ. Все поля — Поля складского документа
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 — Ошибки.

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