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

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

Товарные строки складских документов: какой товар, в каком количестве, по какой закупочной цене и между какими складами движется. У одного документа может быть несколько позиций. Позиции можно менять, пока документ не проведён.

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

Создать позицию складского документа

POST /v1/catalog-document-elements

Добавляет позицию в складской документ.

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

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

Поле Тип Обяз. Описание
docId number да Идентификатор документа. Список: GET /v1/catalog-documents. После создания не меняется
elementId number да Идентификатор товара. Список: GET /v1/catalog-products. После создания не меняется
amount number нет Количество товара
purchasingPrice number нет Закупочная цена за единицу
storeFrom number нет Склад отправления. Список: GET /v1/warehouses. Какой склад нужен документу, зависит от его типа — см. позиции складских документов
storeTo number нет Склад получения. Список: GET /v1/warehouses

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-document-elements" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docId": 299,
    "elementId": 6595,
    "amount": 3,
    "purchasingPrice": 11000,
    "storeTo": 11
  }'

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-document-elements" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "docId": 299,
    "elementId": 6595,
    "amount": 3,
    "purchasingPrice": 11000,
    "storeTo": 11
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-document-elements', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    docId: 299,
    elementId: 6595,
    amount: 3,
    purchasingPrice: 11000,
    storeTo: 11,
  }),
})

const { success, data } = await res.json()
console.log('Position ID:', data.id)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-document-elements', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    docId: 299,
    elementId: 6595,
    amount: 3,
    purchasingPrice: 11000,
    storeTo: 11,
  }),
})

const { success, data } = await res.json()

Поля ответа

HTTP-статус 201 Created.

Поле Тип Описание
success boolean true при успешном создании
data.id number Идентификатор созданной позиции
data.docId number Идентификатор документа. Документ — GET /v1/catalog-documents/:id
data.elementId number Идентификатор товара. Товар — GET /v1/catalog-products/:id
data.amount number | null Количество товара. null, если не передано
data.purchasingPrice number | null Закупочная цена за единицу. null, если не передана
data.storeFrom number | null Склад отправления. null, если не передан. Склады — GET /v1/warehouses
data.storeTo number | null Склад получения. null, если не передан. Склады — GET /v1/warehouses
meta.warnings array Приходит, только если в теле есть поле, которого нет среди полей позиции. Элемент — code: "UNRECOGNIZED_WRITE_FIELD", field с именем поля и message. Объект fields на маршруте, который сам оборачивает карту полей и где схема не объявляет fields, отклоняется с 400 NESTED_FIELDS_ENVELOPE; передавайте поля плоско в корне JSON.

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "amount": 3,
    "docId": 299,
    "elementId": 6595,
    "id": 33,
    "purchasingPrice": 11000,
    "storeFrom": null,
    "storeTo": 11
  }
}

Пример ответа при ошибке

404 — документа с указанным docId нет:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Document not found"
  }
}

Ошибки

HTTP Код Описание
404 ENTITY_NOT_FOUND Документа с указанным docId нет. Сообщение — Document not found
400 MISSING_REQUIRED_FIELDS Не передано обязательное поле. Сообщение называет его: Body field "elementId" is required to create catalogDocumentElement.
400 READONLY_FIELD В теле передан id — поле только для чтения
400 INVALID_PARAMS Значение поля не подходит по типу: нечисловая строка в числовом поле, например "amount": "abc", либо объект или массив вместо числа или строки. Имя поля — в error.message
422 BITRIX_ERROR Документ проведён. Сообщение Conducted document, b24Code — ERROR_DOCUMENT_STATUS. Сначала отмените проведение
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 — Ошибки.

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