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

Поиск складских документов

POST /v1/catalog-documents/search

Ищет складские документы по условиям из тела запроса. Подходит для фильтров с операторами и выборок по диапазону дат. Для выборки без таких условий достаточно списка с фильтром в строке запроса.

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

Поле Тип По умолч. Описание
filter object — Фильтрация по полям GET /v1/catalog-documents/fields.
Синтаксис фильтрации. Пример: {"docType": {"$in": ["A", "S"]}, "status": "N"}
select string[] — Поля в ответе: ["id", "title", "status"]. Принимается и строка через запятую "id,title,status". Имена — из GET /v1/catalog-documents/fields
sort string | object | string[] — Сортировка: "-id" — по убыванию, "id" — по возрастанию, или объект {"id": "desc"}. Принимается и под именем order. Без поля документы идут по возрастанию id
limit number 50 Количество записей, от 1 до 5000. Значение больше 5000 сокращается до 5000
offset number 0 Сколько записей пропустить. Значение больше нуля вместе с разбиением на окна отклоняется — см. UNSTABLE_OFFSET_PAGINATION в разделе «Ошибки»
autoWindow boolean true Разбивать выборку на недельные окна при фильтре по диапазону дат шире 14 дней. false отключает разбиение

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-documents/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "docType": "S", "status": "N" },
    "select": ["id", "title", "docType", "status", "total"],
    "sort": "-id",
    "limit": 2
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-documents/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "docType": "S", "status": "N" },
    "select": ["id", "title", "docType", "status", "total"],
    "sort": "-id",
    "limit": 2
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-documents/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { docType: 'S', status: 'N' },
    select: ['id', 'title', 'docType', 'status', 'total'],
    sort: '-id',
    limit: 2,
  }),
})

const { success, data, meta } = await res.json()
console.log(`Получено непроведённых оприходований: ${data.length}`)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-documents/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { docType: 'S', status: 'N' },
    select: ['id', 'title', 'docType', 'status', 'total'],
    sort: '-id',
    limit: 2,
  }),
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив складских документов (все поля — см. Поля складского документа). При заданном select — только перечисленные поля
meta.total number Точное количество документов под фильтром, если оно известно. При неполном обходе временных окон ключ отсутствует
meta.hasMore boolean Есть ли ещё документы за пределами limit
meta.durationMs number Длительность запроса в миллисекундах
meta.autoWindowed boolean true, если выборка разбита на недельные окна. Приходит только при разбиении
meta.windowCount number Число окон. Приходит при autoWindowed: true
meta.batchWaves number Число волн параллельных запросов по окнам. Приходит при autoWindowed: true
meta.warnings array Предупреждения о запросе. Приходит, когда в select есть имя, которого нет среди полей документа: код UNKNOWN_SELECT_FIELD, имя в поле field. Остальные поля возвращаются

Конец выборки определяйте по meta.hasMore: страница, в которой записей ровно limit, тоже может оказаться последней.

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 299,
      "title": "Корректировка остатков — склад 11",
      "docType": "S",
      "status": "N",
      "total": null
    },
    {
      "id": 151,
      "title": "оприходование 33",
      "docType": "S",
      "status": "N",
      "total": null
    }
  ],
  "meta": {
    "total": 36,
    "hasMore": true,
    "durationMs": 103
  }
}

С фильтром по диапазону дат шире 14 дней, например {"filter": {">=dateCreate": "2025-01-01T00:00:00Z", "<dateCreate": "2025-07-01T00:00:00Z"}}, в meta дополнительно приходят autoWindowed, windowCount и batchWaves:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Оприходование #2",
      "dateCreate": "2025-01-10T11:49:37.000Z"
    },
    {
      "id": 3,
      "title": "Приходная накладная #12",
      "dateCreate": "2025-06-27T05:00:47.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false,
    "autoWindowed": true,
    "windowCount": 26,
    "batchWaves": 1,
    "durationMs": 219
  }
}

В примере выше все окна прочитаны успешно, повторы удалены, поэтому meta.total содержит точное число совпадений. При ранней остановке по limit или неполной выдаче окон ключ meta.total отсутствует. Дополнительный обход только ради счётчика не выполняется. Количество возвращённых документов — data.length; наличие следующих результатов определяет meta.hasMore.

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

400 — фильтр по полю, которого нет у документа:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'bogus' for entity 'catalog-documents'. Available: id, docType, currency, responsibleId, status, dateStatus, createdBy, dateCreate, title, docNumber, commentary, dateDocument, siteId, total, modifiedBy, statusBy, dateModify"
  }
}

Ошибки

HTTP Код Описание
400 UNKNOWN_FILTER_FIELD Фильтр по полю, которого нет у документа. Сообщение перечисляет допустимые поля
400 UNKNOWN_SORT_FIELD Сортировка по полю, которого нет у документа. Сообщение перечисляет допустимые поля
400 INVALID_FILTER_OPERATOR В фильтре передан неподдерживаемый оператор. Сообщение перечисляет поддерживаемые
400 INVALID_SORT_TYPE sort передан не строкой, не объектом и не массивом строк, например числом
400 INVALID_SELECT_TYPE select передан не строкой и не массивом строк, например числом
400 INVALID_LIMIT limit не является числом, например "abc"
400 INVALID_REQUEST Тело запроса — не JSON-объект, например массив
400 UNSTABLE_OFFSET_PAGINATION offset больше нуля вместе с фильтром по диапазону дат шире 14 дней. Возьмите всё одним запросом с limit до 5000, либо передайте autoWindow: false с сортировкой "sort": "id", либо разбейте диапазон дат на части сами
403 SCOPE_DENIED API-ключ не имеет скоупа catalog
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Переданный API-ключ не найден
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Действующее значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After

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

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