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

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

Catalog measures

Reference list of units of measure in the product catalog: pieces, kilograms, liters, and other units in which product quantity is specified. The unit identifier is passed in a product's measure field.

Bitrix24 API: catalog.measure.* Scope: catalog

Create a unit of measure

POST /v1/catalog-measures

Adds a new unit of measure to the product catalog directory so that product quantities can be expressed in it. The request body is flat — no fields wrapper.

Request fields (body)

Field Type Required Description
Fieldcode Typenumber Requiredyes DescriptionUnit code in the Russian National Classifier of Units of Measurement (OKEI), an integer. Unique within the Bitrix24 account. Codes already in use — see GET /v1/catalog-measures
FieldmeasureTitle Typestring Requiredyes DescriptionUnit of measure name
Fieldsymbol Typestring Requiredno DescriptionShort symbol, for example pkg
FieldsymbolIntl Typestring Requiredno DescriptionInternational symbol
FieldsymbolLetterIntl Typestring Requiredno DescriptionInternational letter code, for example PCE
FieldisDefault Typestring Requiredno DescriptionDefault unit: Y or N. If the field is omitted, the unit is created with N

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

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-measures" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": 9917,
    "measureTitle": "Documentation test",
    "symbol": "dt",
    "symbolIntl": "td",
    "symbolLetterIntl": "TDC"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-measures" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": 9917,
    "measureTitle": "Documentation test",
    "symbol": "dt",
    "symbolIntl": "td",
    "symbolLetterIntl": "TDC"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-measures', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 9917,
    measureTitle: 'Documentation test',
    symbol: 'dt',
    symbolIntl: 'td',
    symbolLetterIntl: 'TDC',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-measures', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 9917,
    measureTitle: 'Documentation test',
    symbol: 'dt',
    symbolIntl: 'td',
    symbolLetterIntl: 'TDC',
  }),
})

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

Response fields

The response comes with status 201 and contains the full created record.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionID of the created unit. Pass it in the product's measure field
Fielddata.code Typenumber DescriptionOKEI unit code
Fielddata.measureTitle Typestring DescriptionUnit of measure name
Fielddata.symbol Typestring | null DescriptionShort symbol. null if not provided
Fielddata.symbolIntl Typestring | null DescriptionInternational symbol. null if not provided
Fielddata.symbolLetterIntl Typestring | null DescriptionInternational letter code. null if not provided
Fielddata.isDefault Typestring DescriptionY — default unit, N — not default
Fieldmeta.warnings Typearray DescriptionPresent only if the body contains a field that is not among the unit of measure fields. Each entry carries 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": {
    "code": 9917,
    "id": 17,
    "isDefault": "N",
    "measureTitle": "Documentation test",
    "symbol": "dt",
    "symbolIntl": "td",
    "symbolLetterIntl": "TDC"
  }
}

Error response example

400 — fractional unit code, the record is not created:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field \"code\" must be an integer; Bitrix24 silently truncates fractional values."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptioncode or measureTitle is missing. The message names the first missing field, for example Body field "code" is required to create catalogMeasure.
HTTP400 CodeNESTED_FIELDS_ENVELOPE DescriptionThe body contains an object under fields instead of root-level fields; the unit is not created
HTTP400 CodeINVALID_PARAMS Descriptioncode is not an integer, for example 9917.5
HTTP400 CodeINVALID_PARAMS DescriptionisDefault is neither Y nor N
HTTP422 CodeBITRIX_ERROR DescriptionA unit with this code already exists in the Bitrix24 account. The message is Duplicate entry for key [code], and the response also carries error.b24Code
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 missing

Full list of common API errors — Errors.

Known specifics

An unknown scalar field does not stop creation. If the body contains an unknown scalar field alongside code and measureTitle, the unit is created with status 201, and a warning in meta.warnings reports that the field may not have been saved. An object under fields is rejected with 400 NESTED_FIELDS_ENVELOPE before creation: send fields at the JSON root. Check field names against GET /v1/catalog-measures/fields, and verify the result by checking the values in data, not just success.

See also