Para agentes de IA: markdown desta página — /docs-content-en/entities/catalog-document-elements.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Inventory document items

Product lines of inventory documents: which product moves, in what quantity, at what purchase price, and between which warehouses. One document can have several items. Items can be changed until the document is conducted.

Bitrix24 API: catalog.document.element.* Scope: catalog

Create an inventory document item

POST /v1/catalog-document-elements

Adds an item to an inventory document.

Pass fields flat at the JSON root, without a fields wrapper.

Request fields (body)

Field Type Required Description
FielddocId Typenumber Requiredyes DescriptionDocument ID. List: GET /v1/catalog-documents. Cannot be changed after creation
FieldelementId Typenumber Requiredyes DescriptionProduct ID. List: GET /v1/catalog-products. Cannot be changed after creation
Fieldamount Typenumber Requiredno DescriptionProduct quantity
FieldpurchasingPrice Typenumber Requiredno DescriptionPurchase price per unit
FieldstoreFrom Typenumber Requiredno DescriptionSource warehouse. List: GET /v1/warehouses. Which warehouse a document needs depends on its type — see inventory document items
FieldstoreTo Typenumber Requiredno DescriptionDestination warehouse. List: GET /v1/warehouses

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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 application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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 — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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 application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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()

Response fields

HTTP status 201 Created.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on successful creation
Fielddata.id Typenumber DescriptionID of the created item
Fielddata.docId Typenumber DescriptionDocument ID. Document — GET /v1/catalog-documents/:id
Fielddata.elementId Typenumber DescriptionProduct ID. Product — GET /v1/catalog-products/:id
Fielddata.amount Typenumber | null DescriptionProduct quantity. null if not passed
Fielddata.purchasingPrice Typenumber | null DescriptionPurchase price per unit. null if not passed
Fielddata.storeFrom Typenumber | null DescriptionSource warehouse. null if not passed. Warehouses — GET /v1/warehouses
Fielddata.storeTo Typenumber | null DescriptionDestination warehouse. null if not passed. Warehouses — GET /v1/warehouses
Fieldmeta.warnings Typearray DescriptionPresent only if the body contains a field that is not among the item fields. Each element has code: "UNRECOGNIZED_WRITE_FIELD", field with the field name, and message. On a route that wraps the field map itself, an object under fields is rejected with 400 NESTED_FIELDS_ENVELOPE when the schema does not declare fields; pass fields flat at the JSON root.

Response example

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

Error response example

404 — no document with the given docId:

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

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo document with the given docId. Message — Document not found
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionA required field was not passed. The message names it: Body field "elementId" is required to create catalogDocumentElement.
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains id, a read-only field
HTTP400 CodeINVALID_PARAMS DescriptionA field value has the wrong type: a non-numeric string in a numeric field, for example "amount": "abc", or an object or array instead of a number or string. The field name is in error.message
HTTP422 CodeBITRIX_ERROR DescriptionThe document is conducted. Message Conducted document, b24Code — ERROR_DOCUMENT_STATUS. First cancel conducting
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key works in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the catalog scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe passed API key was not found

Full list of common API errors — Errors.

See also