Для AI-агентов: markdown этой страницы — /docs-content/entities/catalog-vat-rates/search.md индекс документации — /llms.txt

Поиск ставок НДС

POST /v1/catalog-vat-rates/search

Ищет ставки НДС торгового каталога по условиям в JSON-теле запроса. Условия по нескольким полям задаются вложенной структурой в теле запроса.

Поля запроса (body)

Поле Тип Обяз. Описание
filter object нет Фильтрация по полям GET /v1/catalog-vat-rates/fields.
Синтаксис фильтрации. Пример: {"active": "Y"}.
sort string | object | array нет Строка "-rate", объект {"rate": "desc"} или массив строк ["-rate", "id"]. Без поля — по возрастанию id.
order object нет Синоним sort в форме объекта. При передаче обоих применяется sort.
select string[] нет Выборка полей: ["id", "name", "rate"]. Принимается и строка "id,name,rate".
limit number нет Количество записей, от 1 до 5000. По умолчанию 50.
offset number нет Пропустить N записей. По умолчанию 0.
withTotal boolean нет Запросить количество записей. Для этого справочника false не отключает meta.total.
autoWindow boolean нет Автоматическое разбиение больших выборок по датам. По умолчанию включено. Для небольшого справочника используйте обычные limit и offset.

Примеры

curl — личный ключ

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-vat-rates/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filter": {
    "id": 25
  },
  "sort": "-rate",
  "limit": 2
}'

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-vat-rates/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "filter": {
    "id": 25
  },
  "sort": "-rate",
  "limit": 2
}'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-vat-rates/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter": {
      "id": 25
    },
    "sort": "-rate",
    "limit": 2
  }),
})

const { success, data, meta } = await res.json()
console.log(data, meta.hasMore)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-vat-rates/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter": {
      "id": 25
    },
    "sort": "-rate",
    "limit": 2
  }),
})

const { success, data, meta } = await res.json()
console.log(data, meta.hasMore)

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе.
data array Массив ставок НДС.
data[].id number Идентификатор ставки. Список: GET /v1/catalog-vat-rates. Его передают в поле vatId товара.
data[].name string Название ставки.
data[].rate number | null Процент НДС. У существующей ставки «Без НДС» может быть null.
data[].active string Активность ставки: Y — активна, N — неактивна.
data[].sort number Порядок сортировки.
data[].timestampX string Дата и время изменения в формате ISO 8601. Заполняется Битрикс24.
meta.total number Количество ставок под фильтром. Приходит в том числе при withTotal=false.
meta.hasMore boolean Есть ли ещё ставки за пределами limit.
meta.durationMs number Длительность запроса в миллисекундах.
meta.warnings array Появляется при предупреждениях: UNKNOWN_SELECT_FIELD — неизвестное имя в select, LIMIT_ZERO_IGNORED — limit равен 0, применяется значение по умолчанию.

Пример ответа

JSON 
{
  "success": true,
  "data": [
    {
      "active": "N",
      "id": 25,
      "name": "Docs VAT 2026-10-08",
      "rate": 7.5,
      "sort": 900,
      "timestampX": "2026-10-08T18:49:59.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false,
    "durationMs": 80
  }
}

Пример ответа при ошибке

400 — сортировка по полю nope, которого нет в схеме:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_SORT_FIELD",
    "message": "Unknown sort field 'nope' for entity 'catalog-vat-rates'. Available: id, name, rate, active, sort, timestampX"
  }
}

Ошибки

HTTP Код Описание
400 UNKNOWN_FILTER_FIELD Фильтр по полю вне схемы. Сообщение перечисляет доступные поля.
400 UNKNOWN_SORT_FIELD Сортировка по полю вне схемы.
400 INVALID_FILTER_OPERATOR Неизвестный оператор или логический ключ $or, $and, $not. Для нескольких значений одного поля используйте $in.
400 INVALID_FILTER filter не является объектом условий.
400 INVALID_SORT_TYPE sort не строка, не объект и не массив строк.
400 INVALID_SELECT_TYPE select не строка и не массив строк.
400 INVALID_LIMIT limit не число.
403 SCOPE_DENIED У ключа нет скоупа catalog.
401 MISSING_API_KEY Не передан заголовок X-Api-Key.
401 TOKEN_MISSING У ключа нет настроенных токенов Битрикс24. Для ключа OAuth-приложения проверьте пользовательскую сессию.

Полный список общих ошибок API — Ошибки.

Известные особенности

Пустой объект {} допустим. Без условий поиск возвращает обычный список ставок.

Неизвестное имя в select не останавливает запрос. Проверьте meta.warnings: код UNKNOWN_SELECT_FIELD указывает на поле, которое может отсутствовать в выдаче.

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