Для AI-агентов: markdown этой страницы — /docs-content/entities/documents/list.md индекс документации — /llms.txt
Список документов
GET /v1/documents
Возвращает список документов с поддержкой фильтрации, сортировки, выбора полей и автоматической пагинации.
Параметры
| Параметр | Тип | По умолч. | Описание |
|---|---|---|---|
Параметрlimit |
Типnumber | По умолч.50 |
ОписаниеКоличество записей (до 5000). При limit > 50 Вайбкод автоматически запрашивает несколько страниц |
Параметрoffset |
Типnumber | По умолч.0 |
ОписаниеПропустить N записей. При offset ≥ 2500 рекомендуется limit ≤ 500 |
Параметрselect |
Типstring | По умолч.— | ОписаниеВыборка полей из GET /v1/documents/fields: ?select=id,title,number |
Параметрsort |
Типstring | По умолч.— | ОписаниеСортировка кратким синтаксисом: ?sort=-id, минус означает убывание. Если поля нет в GET /v1/documents/fields, запрос возвращает 400 UNKNOWN_SORT_FIELD |
Параметрorder |
Типobject | По умолч.— | ОписаниеСортировка: ?order[id]=desc. Даёт тот же порядок, что и sort |
Параметрfilter |
Типobject | По умолч.— | ОписаниеФильтрация по полям GET /v1/documents/fields.Синтаксис фильтрации. Пример: ?filter[templateId]=53, идентификатор шаблона — из GET /v1/doc-templates |
Примеры
curl — личный ключ
curl -g "https://vibecode.bitrix24.tech/v1/documents?limit=10&order[id]=desc&filter[templateId]=53" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl -g "https://vibecode.bitrix24.tech/v1/documents?limit=10&order[id]=desc&filter[templateId]=53" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/documents?limit=10&order[id]=desc&filter[templateId]=53', {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
},
})
const { success, data, meta } = await res.json()
console.log(`Найдено ${meta.total} документов`)
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/documents?limit=10&order[id]=desc&filter[templateId]=53', {
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
},
})
const { success, data, meta } = await res.json()
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata |
Типarray | ОписаниеМассив документов (все поля элемента — см. Поля документа) |
Полеmeta.total |
Типnumber | ОписаниеКоличество записей, соответствующих фильтру |
Полеmeta.hasMore |
Типboolean | ОписаниеЕсть ли ещё записи за пределами limit |
Пример ответа
{
"success": true,
"data": [
{
"id": 51,
"title": "Договор поставки 2026-001",
"number": "2026-001",
"templateId": 53,
"provider": "Bitrix\\DocumentGenerator\\DataProvider\\Rest",
"value": "ORDER-1024",
"fileId": 241,
"pdfId": 245,
"imageId": 243,
"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,
"downloadUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=documentgenerator.api.document.getfile&id=51",
"pdfUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=documentgenerator.api.document.getpdf&id=51",
"imageUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=documentgenerator.api.document.getimage&id=51"
},
{
"id": 52,
"title": "Договор поставки 2026-002",
"number": "2026-002",
"templateId": 53,
"provider": "Bitrix\\DocumentGenerator\\DataProvider\\Rest",
"value": "ORDER-1025",
"fileId": 248,
"pdfId": 250,
"imageId": 249,
"createTime": "2026-03-19T10:12:03+03:00",
"updateTime": "2026-03-19T10:12:03+03:00",
"createdBy": 503,
"updatedBy": null,
"values": { "DocumentNumber": "2026-002" },
"stampsEnabled": false,
"downloadUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=documentgenerator.api.document.getfile&id=52",
"pdfUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=documentgenerator.api.document.getpdf&id=52",
"imageUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=documentgenerator.api.document.getimage&id=52"
}
],
"meta": { "total": 2, "hasMore": false }
}
Пример ответа при ошибке
400 — фильтр по несуществующему полю:
{
"success": false,
"error": {
"code": "UNKNOWN_FILTER_FIELD",
"message": "Unknown filter field 'zzzNope' for entity 'documents'. Available: id, title, number, templateId, providerClassName, value, values, fields, createTime, updateTime, fileId, pdfId, imageId, stampsEnabled, provider, downloadUrl, pdfUrl, imageUrl, downloadUrlMachine, pdfUrlMachine, imageUrlMachine, createdBy, updatedBy, publicUrl"
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодUNKNOWN_FILTER_FIELD |
ОписаниеФильтр по полю, которого нет у документа. Список полей — GET /v1/documents/fields |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеКлючу не хватает скоупа documentgenerator |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP429 | КодRATE_LIMITED |
ОписаниеПревышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Действующее значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After |
Полный список общих ошибок API — Ошибки.
Известные особенности
Поле publicUrl доступно только в ответе GET /v1/documents/:id, в списке оно не приходит.
При limit > 50 Вайбкод запрашивает несколько страниц и собирает все записи в один ответ. За один вызов возвращается не более 5000 записей.
При offset ≥ 2500 для устойчивости запроса используйте limit ≤ 500.
Для сложных фильтров с множеством условий параметры передаются в теле запроса — POST /v1/documents/search. Этот эндпоинт также поддерживает оконный поиск по датам для больших выборок. См. Поиск документов.