# Единицы измерения каталога

Справочник единиц измерения торгового каталога: штуки, килограммы, литры и другие единицы, в которых указывается количество товара. Идентификатор единицы передаётся в поле `measure` товара.

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

## Операции

- [Создать единицу измерения](./catalog-measures/create.md) — `POST /v1/catalog-measures`
- [Список единиц измерения](./catalog-measures/list.md) — `GET /v1/catalog-measures`
- [Получить единицу измерения](./catalog-measures/get.md) — `GET /v1/catalog-measures/:id`
- [Обновить единицу измерения](./catalog-measures/update.md) — `PATCH /v1/catalog-measures/:id`
- [Удалить единицу измерения](./catalog-measures/delete.md) — `DELETE /v1/catalog-measures/:id`
- [Поиск единиц измерения](./catalog-measures/search.md) — `POST /v1/catalog-measures/search`
- [Поля единицы измерения](./catalog-measures/fields.md) — `GET /v1/catalog-measures/fields`

## Ключевые поля

| Поле | Описание |
|------|---------|
| `id` | Идентификатор единицы измерения. Его передают в поле `measure` товара |
| `code` | Код единицы по Общероссийскому классификатору единиц измерения (ОКЕИ), целое число. Уникален на портале |
| `measureTitle` | Название единицы измерения |
| `symbol` | Краткое обозначение |
| `symbolIntl` | Международное обозначение |
| `symbolLetterIntl` | Международное буквенное обозначение |
| `isDefault` | Единица по умолчанию: `Y` или `N` |

Полный список полей — [`GET /v1/catalog-measures/fields`](./catalog-measures/fields.md).

## Что нужно знать перед работой

1. **Тело запроса плоское.** При создании и обновлении поля передаются в корне JSON: `{"code": 9001, "measureTitle": "Упаковка"}`. Обёртка `fields` не нужна.
2. **Для создания нужны два поля:** `code` и `measureTitle`. Код уникален на портале: повтор существующего `code` возвращает `422 BITRIX_ERROR` с сообщением `Duplicate entry for key [code]`.
3. **Название бывает пустым.** У части единиц `measureTitle` и `symbol` приходят как `null`, а обозначение заполнено только в `symbolIntl` и `symbolLetterIntl`. На проверенном портале так выглядят пять стандартных единиц: метр, литр, грамм, килограмм и штука. Для отображения берите `measureTitle`, а при `null` — `symbolIntl`.
4. **Единица по умолчанию одна.** Значение `isDefault: "Y"` стоит ровно у одной единицы портала.
5. **Значения проверяются до записи.** Дробный `code` и `isDefault` вне `Y` и `N` отклоняются с `400 INVALID_PARAMS`, запись не создаётся и не меняется.
6. **Пакетная запись не принимает `null`.** Поле со значением `null` в пакете отклоняется: `POST /v1/catalog-measures/batch` отвечает `400 BATCH_ITEM_VALIDATION`, а вызов в `POST /v1/batch` отклоняется с кодом `INVALID_PARAMS` в `data.errors`. Чтобы очистить `symbol`, `symbolIntl` или `symbolLetterIntl`, отправьте одиночный [`PATCH /v1/catalog-measures/:id`](./catalog-measures/update.md).

## Типичный сценарий

Добавление товара в своей единице измерения:

1. Проверить, есть ли нужная единица: [`GET /v1/catalog-measures?filter[code]=778`](./catalog-measures/list.md).
2. Если её нет — создать: [`POST /v1/catalog-measures`](./catalog-measures/create.md) с `code` и `measureTitle`, взять `id` из ответа.
3. Передать этот `id` в поле `measure` при создании товара: [`POST /v1/catalog-products`](/docs/entities/catalog-products/create).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Автоматическая пагинация | включается при `limit > 50` |
| Пакет по одной сущности | [`POST /v1/catalog-measures/batch`](/docs/entity-api) — действия записи `create`, `update`, `delete` |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Товары каталога](/docs/entities/catalog-products)
- [Товары CRM](/docs/entities/products)
- [Ставки НДС каталога](/docs/entities/catalog-vat-rates)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Справочник API](/docs/api-reference)