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

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

POST /v1/documents/search

Возвращает документы по фильтру, переданному в теле запроса. Аналогичен GET /v1/documents с фильтрами, но условия отбора передаются в теле запроса — это удобнее для сложных выборок с большим количеством условий.

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

Поле Тип По умолч. Описание
filter object — Отбор по полям документа.
Синтаксис фильтрации. Пример: { "filter": { "templateId": 53 } }
limit number 50 Количество документов в ответе, до 5000
offset number 0 Пропустить указанное число документов. Вместе с фильтром по диапазону дат шире 14 дней отклоняется — см. UNSTABLE_OFFSET_PAGINATION в разделе «Ошибки»
sort object — Сортировка: { "id": "desc" }. Допустимы те же поля, что и в filter
select string[] — Выборка полей: ["id", "title", "number"]. В ответе остаются только перечисленные поля и id
autoWindow boolean true Разбивать выборку по недельным окнам при фильтре по диапазону дат шире 14 дней. false отключает разбиение

Имена полей для filter, sort и select — из Полей документа.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/documents/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "templateId": 53 },
    "limit": 10,
    "sort": { "id": "desc" }
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/documents/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "templateId": 53 },
    "limit": 10,
    "sort": { "id": "desc" }
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/documents/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { templateId: 53 },
    limit: 10,
    sort: { id: 'desc' },
  }),
})

const { data, meta } = await res.json()
console.log('Найдено:', meta.total)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/documents/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { templateId: 53 },
    limit: 10,
    sort: { id: 'desc' },
  }),
})

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

Поля ответа

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

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 51,
      "title": "Договор поставки 2026-001",
      "number": "2026-001",
      "templateId": 53,
      "provider": "Bitrix\\DocumentGenerator\\DataProvider\\Rest",
      "value": "ORDER-1024",
      "createTime": "2026-03-18T17:27:48+03:00",
      "updateTime": "2026-03-18T17:27:48+03:00",
      "createdBy": 503,
      "updatedBy": null,
      "values": { "DocumentNumber": "2026-001" },
      "stampsEnabled": false,
      "pdfUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=documentgenerator.api.document.getpdf&id=51"
    }
  ],
  "meta": { "total": 1, "hasMore": false, "durationMs": 42 }
}

Когда под фильтр не попал ни один документ, data приходит пустым массивом, а meta.total равен 0:

JSON 
{
  "success": true,
  "data": [],
  "meta": { "total": 0, "hasMore": false, "durationMs": 644 }
}

С фильтром по диапазону дат шире 14 дней в meta дополнительно приходят autoWindowed, windowCount и batchWaves:

JSON 
{
  "success": true,
  "data": [],
  "meta": {
    "total": 0,
    "hasMore": false,
    "autoWindowed": true,
    "windowCount": 339,
    "batchWaves": 7,
    "durationMs": 7890
  }
}

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

400 — поле в filter не входит в список полей документа:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'notArealField' for entity 'documents'."
  }
}

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

Имя поля в filter и sort сверяется со списком полей документа до обращения к данным. Неизвестное поле в filter возвращает 400 UNKNOWN_FILTER_FIELD, неизвестное поле в sort — 400 UNKNOWN_SORT_FIELD. В обоих случаях сообщение перечисляет допустимые имена полей.

Разбиение по временны́м окнам. Фильтр по диапазону дат шире 14 дней (поля createTime или updateTime) автоматически разбивается на недельные окна, которые выполняются параллельными волнами — так выборка обходит потолок в 5000 документов на один вызов. В meta тогда приходят autoWindowed: true, число окон windowCount и число волн batchWaves. Отключает разбиение параметр autoWindow: false. При активном разбиении offset больше нуля отклоняется с UNSTABLE_OFFSET_PAGINATION.

Ошибки

HTTP Код Описание
400 UNKNOWN_FILTER_FIELD Поле в filter не входит в список полей документа
400 UNKNOWN_SORT_FIELD Поле в sort не входит в список полей документа
400 UNSTABLE_OFFSET_PAGINATION offset больше нуля вместе с фильтром по диапазону дат шире 14 дней. Два разных алгоритма выдачи дают несогласованные результаты, поэтому запрос отклоняется. Возьмите всё одним запросом с limit до 5000, либо передайте autoWindow: false с сортировкой по id, либо режьте диапазон дат на части сами
403 SCOPE_DENIED Ключу не хватает скоупа documentgenerator
401 MISSING_API_KEY Не передан заголовок X-Api-Key

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

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