# Ставки НДС каталога

Справочник ставок НДС торгового каталога: названия, проценты, активность и порядок сортировки. Идентификатор ставки передаётся в поле `vatId` товара.

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

## Операции

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

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

| Поле | Описание |
|------|------|
| `id` | Идентификатор ставки. Список: [`GET /v1/catalog-vat-rates`](/docs/entities/catalog-vat-rates/list). Его передают в поле `vatId` товара. |
| `name` | Название ставки. |
| `rate` | Процент НДС. У существующей ставки «Без НДС» может быть `null`. |
| `active` | Активность ставки: `Y` — активна, `N` — неактивна. |
| `sort` | Порядок сортировки. |
| `timestampX` | Дата и время изменения в формате ISO 8601. Заполняется Битрикс24. |

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

1. **Тело запроса плоское.** При создании и обновлении поля передаются в корне JSON, без обёртки `fields`.
2. **Для создания нужны `name` и `rate`.** Процент может быть дробным или равным `0`. Создание с `rate: null` возвращает `400 MISSING_REQUIRED_FIELDS`.
3. **Ставка «Без НДС» может иметь `rate: null`.** Это значение встречается в существующих записях и отличается от числовой ставки `0`. PATCH с `rate: null` возвращает `422 BITRIX_ERROR` с сообщением `Required fields: rate`.
4. **Одиночный PATCH принимает только изменяемые поля.** Пропущенные `name` и `rate` подставляются из текущей записи. В пакетном обновлении оба поля нужно передать в каждом элементе.
5. **Значения проверяются до записи.** `active` принимает `Y` или `N`, `sort` — целое число не меньше `1`. Поля `id` и `timestampX` доступны только для чтения, в теле они возвращают `400 READONLY_FIELD`.
6. **Перед удалением проверьте товары со ставкой.** Найдите их по `vatId` через [список товаров каталога](/docs/entities/catalog-products/list). Если нужно сохранить запись с числовым `rate`, выключите ставку через `active: "N"`. У существующей ставки «Без НДС» с `rate: null` такой PATCH вернёт `422 BITRIX_ERROR` с сообщением `Required fields: rate`. Запись останется активной. PATCH только с полем `active` не может деактивировать её, пока `rate` остаётся равным `null`.

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

Настройка ставки для товара:

1. Найти ставку через [`GET /v1/catalog-vat-rates?filter[active]=Y`](./catalog-vat-rates/list.md) или [поиск](./catalog-vat-rates/search.md).
2. Если нужной ставки нет, [создать её](./catalog-vat-rates/create.md).
3. Передать полученный `id` в `vatId` при [создании товара каталога](/docs/entities/catalog-products/create).
4. Для изменения названия или процента отправить [PATCH ставки](./catalog-vat-rates/update.md), затем [прочитать её](./catalog-vat-rates/get.md) и проверить результат.

## Лимиты

Список и поиск принимают `limit` от 1 до 5000, по умолчанию `50`. Для обхода используйте `offset` и `meta.hasMore`. Вайбкод автоматически получает дополнительные страницы при `limit > 50`.

Пакетная запись доступна через `POST /v1/catalog-vat-rates/batch` и универсальный `POST /v1/batch`. Порядок вызовов — в [Пакетных вызовах](/docs/batch). Агрегация для этого справочника недоступна.

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

- [Поля ставки НДС](/docs/entities/catalog-vat-rates/fields)
- [Товары каталога](/docs/entities/catalog-products)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Лимиты и оптимизация](/docs/optimization)