Для 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 |
ОписаниеПропустить N записей. Положительное значение отклоняется только при активном разбиении по датам — см. UNSTABLE_OFFSET_PAGINATION в разделе «Ошибки» |
Полеstart |
Типnumber | По умолч.0 |
ОписаниеТо же значение смещения, что offset. Если заданы оба поля, действует offset, включая 0; при offset: null действует start. |
Полеsort |
Типobject | По умолч.— | ОписаниеСортировка: { "id": "desc" }. Допустимы те же поля, что и в filter |
Полеselect |
Типstring[] | По умолч.— | ОписаниеВыборка полей: ["id", "title", "number"]. В ответе остаются только перечисленные поля и id |
ПолеautoWindow |
Типboolean | По умолч.true |
ОписаниеРазбивать выборку по недельным окнам при фильтре по диапазону дат шире 14 дней. false отключает разбиение |
Имена полей для filter, sort и select — из Полей документа.
Примеры
curl — личный ключ
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-приложение
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 — личный ключ
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-приложение
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 |
Пример ответа
{
"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:
{
"success": true,
"data": [],
"meta": { "total": 0, "hasMore": false, "durationMs": 644 }
}
С фильтром по диапазону дат шире 14 дней в meta дополнительно приходят autoWindowed, windowCount и batchWaves:
{
"success": true,
"data": [],
"meta": {
"total": 0,
"hasMore": false,
"autoWindowed": true,
"windowCount": 339,
"batchWaves": 7,
"durationMs": 7890
}
}
Пример ответа при ошибке
400 — поле в filter не входит в список полей документа:
{
"success": false,
"error": {
"code": "UNKNOWN_FILTER_FIELD",
"message": "Unknown filter field 'notArealField' for entity 'documents'."
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодUNKNOWN_FILTER_FIELD |
ОписаниеПоле в filter не входит в список полей документа |
| HTTP400 | КодUNKNOWN_SORT_FIELD |
ОписаниеПоле в sort не входит в список полей документа |
| HTTP400 | КодUNSTABLE_OFFSET_PAGINATION |
ОписаниеДействующее смещение (offset, если передан и не равен null, иначе start) больше нуля при активном разбиении по датам. Два разных алгоритма выдачи дают несогласованные результаты, поэтому запрос отклоняется. Возьмите всё одним запросом с limit до 5000, либо передайте autoWindow: false с сортировкой по id, либо режьте диапазон дат на части сами |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеКлючу не хватает скоупа documentgenerator |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP429 | КодRATE_LIMITED |
ОписаниеПревышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Действующее значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After |
Полный список общих ошибок API — Ошибки.
Известные особенности
Имя поля в filter и sort сверяется со списком полей документа до обращения к данным. Неизвестное поле в filter возвращает 400 UNKNOWN_FILTER_FIELD, неизвестное поле в sort — 400 UNKNOWN_SORT_FIELD. В обоих случаях сообщение перечисляет допустимые имена полей.
Разбиение по временны́м окнам. Фильтр по диапазону дат шире 14 дней (поля createTime или updateTime) автоматически разбивается на недельные окна, которые выполняются параллельными волнами — так выборка обходит потолок в 5000 документов на один вызов. В meta тогда приходят autoWindowed: true, число окон windowCount и число волн batchWaves. Отключает разбиение параметр autoWindow: false. При активном разбиении действующее смещение больше нуля отклоняется с UNSTABLE_OFFSET_PAGINATION.