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

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

Inventory documents

Inventory management documents: goods receipt, stock adjustment, transfer between warehouses, return and write-off. A document is a header with a type, a currency and a responsible user. Products and warehouses are set by its items. Warehouse stock changes when the document is conducted and reverts when conducting is canceled.

Bitrix24 API: catalog.document.* Scope: catalog

Create an inventory document

POST /v1/catalog-documents

Creates an inventory document — the header of a receipt, stock adjustment, transfer, return or write-off.

Fields are passed flat at the JSON root, without a fields wrapper.

Request fields (body)

Field Type Required Description
FielddocType Typestring Requiredyes DescriptionDocument type: A — receipt, S — stock adjustment, M — transfer, R — return, D — write-off. Cannot be changed after creation. More on the types — Inventory documents
Fieldcurrency Typestring Requiredyes DescriptionDocument currency. Cannot be changed after creation. List: GET /v1/currencies
FieldresponsibleId Typenumber Requiredyes DescriptionResponsible employee. List: GET /v1/users
Fieldtitle Typestring Requiredno DescriptionDocument title
FielddocNumber Typestring Requiredno DescriptionDocument number
Fieldcommentary Typestring Requiredno DescriptionComment
FielddateDocument Typedatetime Requiredno DescriptionDocument date
Fieldtotal Typenumber Requiredno DescriptionDocument total. Not calculated from the document items: after conducting, the field holds the passed value or null
FieldsiteId Typestring Requiredno DescriptionBitrix24 site ID. If omitted at creation, s1 is used
FieldcreatedBy Typenumber Requiredno DescriptionEmployee who created the document. Cannot be changed after creation. List: GET /v1/users
FieldmodifiedBy Typenumber Requiredno DescriptionEmployee who last modified the document. List: GET /v1/users
FieldstatusBy Typenumber Requiredno DescriptionEmployee who last changed the conducting status. List: GET /v1/users
FielddateModify Typedatetime Requiredno DescriptionLast modification date

Full field list — GET /v1/catalog-documents/fields.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-documents" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docType": "S",
    "currency": "USD",
    "responsibleId": 1,
    "title": "Stock correction — documentation check"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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": "USD",
    "responsibleId": 1,
    "title": "Stock correction — documentation check"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-documents', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    docType: 'S',
    currency: 'USD',
    responsibleId: 1,
    title: 'Stock correction — documentation check',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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: 'USD',
    responsibleId: 1,
    title: 'Stock correction — documentation check',
  }),
})

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

Response fields

HTTP status 201 Created.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on successful creation
Fielddata Typeobject DescriptionThe created document. All fields — Inventory document fields
Fielddata.id Typenumber DescriptionID of the created document
Fielddata.status Typestring DescriptionConducting status. A new document always has N — not conducted
Fielddata.dateCreate Typedatetime DescriptionCreation date, ISO 8601 in UTC
Fielddata.dateStatus Typedatetime DescriptionDate of the last status change. For a new document it equals dateCreate
Fielddata.dateModify Typedatetime DescriptionLast modification date
Fieldmeta.warnings Typearray DescriptionReturned only if the body contains a field that is not among the document fields. Each item 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": {
    "commentary": null,
    "createdBy": 1,
    "currency": "USD",
    "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": "Stock correction — documentation check",
    "total": null
  }
}

Error response example

400 — a required field is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Body field \"currency\" is required to create catalogDocument."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionOne of the fields docType, currency, responsibleId is missing. The field name is in error.message
HTTP400 CodeREADONLY_FIELD DescriptionA system-set field is passed: id, status, dateStatus, dateCreate
HTTP400 CodeINVALID_PARAMS DescriptionThe field value has the wrong type: a non-numeric string in a numeric field, for example "responsibleId": "abc", or an object or array instead of a number or string. The field name is in error.message
HTTP422 CodeBITRIX_ERROR DescriptiondocType contains a code that is not one of the five types. Message DOC_TYPE isn't available
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 is not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe passed API key is not found

Full list of common API errors — Errors.

See also