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

POST /v1/documents/search

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

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

Поле Тип По умолч. Описание
filter object — Отбор по полям документа.
Синтаксис фильтрации. Пример: { "filter": { "templateId": 53 } }
limit number 50 Количество документов в ответе, до 5000
offset number 0 Пропустить указанное число документов
sort object — Сортировка: { "id": "desc" }. Допустимы те же поля, что и в filter
select string[] — Выборка полей: ["id", "title", "number"]. В ответе остаются только перечисленные поля и id
autoWindow boolean true Разбиение выборки по датам при фильтре с полями createTime / updateTime. Передайте 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 Присутствует, когда выборка разбита по датам
meta.windowCount number Количество подзапросов при разбиении по датам

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

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 }
}

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

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; в обоих случаях сообщение перечисляет допустимые имена полей.

Разбиение по датам. При фильтре с полями createTime или updateTime выборка делится на подзапросы по интервалам дат, и в meta появляются autoWindowed и windowCount. Передайте autoWindow: false, чтобы выполнить один запрос без разбиения.

#Ошибки

HTTP Код Описание
400 UNKNOWN_FILTER_FIELD Поле в filter не входит в список полей документа
400 UNKNOWN_SORT_FIELD Поле в sort не входит в список полей документа
403 SCOPE_DENIED Ключу не хватает скоупа documentgenerator
401 MISSING_API_KEY Не передан заголовок X-Api-Key

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

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