Для AI-агентов: markdown этой страницы — /docs-content/entities/documents/fields.md индекс документации — /llms.txt
Поля документа
GET /v1/documents/fields
Возвращает полную схему полей документа: имя поля, тип, признак «только для чтения» и обязательность при создании. Поля помечены ★ — обязательны в теле запроса при создании документа.
Примеры
curl — личный ключ
curl "https://vibecode.bitrix24.tech/v1/documents/fields" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl "https://vibecode.bitrix24.tech/v1/documents/fields" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/documents/fields', {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
},
})
const { success, data } = await res.json()
console.log('Всего полей:', Object.keys(data.fields).length)
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/documents/fields', {
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
},
})
const { success, data } = await res.json()
Поля ответа
data.fields — объект, ключ которого совпадает с именем поля, а значение содержит type (тип поля), readonly (true — поле нельзя передать при создании и обновлении), required (true — поле обязательно при создании, у остальных полей ключа нет), nullable (true — поле может прийти со значением null), label (отображаемое название) и description (краткое описание). Значения label/description приходят на русском языке. Заголовками запроса язык не переключается. data.batch — массив операций документа, доступных в пакетном запросе.
| Поле | Битрикс24 | Тип | RO | Описание |
|---|---|---|---|---|
Полеid |
Битрикс24id |
Типnumber | ROда | ОписаниеИдентификатор документа |
Полеtitle |
Битрикс24title |
Типstring | RO | ОписаниеНазвание документа |
Полеnumber |
Битрикс24number |
Типstring | RO | ОписаниеНомер документа |
ПолеtemplateId |
Битрикс24templateId |
Типnumber | RO | Описание★ Идентификатор шаблона. Список: GET /v1/doc-templates |
ПолеproviderClassName |
Битрикс24providerClassName |
Типstring | RO | Описание★ Класс провайдера данных, например Bitrix\DocumentGenerator\DataProvider\Rest |
Полеvalue |
Битрикс24value |
Типstring | RO | Описание★ Внешний идентификатор объекта-источника, из которого подставляются данные |
Полеvalues |
Битрикс24values |
Типobject | RO | ОписаниеЗначения полей-меток шаблона |
Полеfields |
Битрикс24fields |
Типobject | RO | ОписаниеОписание форматирования полей |
ПолеcreateTime |
Битрикс24createTime |
Типdatetime | ROда | ОписаниеДата создания |
ПолеupdateTime |
Битрикс24updateTime |
Типdatetime | ROда | ОписаниеДата последнего изменения |
ПолеfileId |
Битрикс24fileId |
Типnumber | RO | ОписаниеИдентификатор файла DOCX |
ПолеpdfId |
Битрикс24pdfId |
Типnumber | RO | ОписаниеИдентификатор файла PDF |
ПолеimageId |
Битрикс24imageId |
Типnumber | RO | ОписаниеИдентификатор файла изображения |
ПолеstampsEnabled |
Битрикс24stampsEnabled |
Типboolean | RO | ОписаниеВключены ли печати и подписи |
Полеprovider |
Битрикс24provider |
Типstring | ROда | ОписаниеКласс провайдера данных документа |
ПолеdownloadUrl |
Битрикс24downloadUrl |
Типstring | ROда | ОписаниеСсылка на скачивание DOCX для пользователя |
ПолеpdfUrl |
Битрикс24pdfUrl |
Типstring | ROда | ОписаниеСсылка на скачивание PDF для пользователя |
ПолеimageUrl |
Битрикс24imageUrl |
Типstring | ROда | ОписаниеСсылка на изображение для пользователя |
ПолеdownloadUrlMachine |
Битрикс24downloadUrlMachine |
Типstring | ROда | ОписаниеАдрес скачивания DOCX через Вайбкод: /v1/documents/:id/download. Нужен X-Api-Key со скоупом documentgenerator |
ПолеpdfUrlMachine |
Битрикс24pdfUrlMachine |
Типstring | ROда | ОписаниеАдрес скачивания PDF через Вайбкод: /v1/documents/:id/pdf. Нужен X-Api-Key со скоупом documentgenerator. Поля нет, пока PDF формируется |
ПолеimageUrlMachine |
Битрикс24imageUrlMachine |
Типstring | ROда | ОписаниеАдрес скачивания изображения через Вайбкод: /v1/documents/:id/image. Нужен X-Api-Key со скоупом documentgenerator. Поля нет, пока изображение формируется |
ПолеcreatedBy |
Битрикс24createdBy |
Типnumber | ROда | ОписаниеИдентификатор создавшего пользователя. Список: GET /v1/users |
ПолеupdatedBy |
Битрикс24updatedBy |
Типnumber | null | ROда | ОписаниеИдентификатор изменившего пользователя. null, если документ не изменялся. Список: GET /v1/users |
ПолеpublicUrl |
Битрикс24publicUrl |
Типstring | null | ROда | ОписаниеПубличная ссылка на документ. null, если публичная ссылка не сформирована |
ПолеisTransformationError |
Битрикс24isTransformationError |
Типboolean | null | ROда | ОписаниеПроизошла ли ошибка при преобразовании документа в PDF |
ПолеtransformationErrorCode |
Битрикс24transformationErrorCode |
Типstring | null | ROда | ОписаниеКод ошибки преобразования в PDF. Пустая строка приходит как null |
ПолеtransformationErrorMessage |
Битрикс24transformationErrorMessage |
Типstring | null | ROда | ОписаниеСообщение об ошибке преобразования в PDF. Пустая строка приходит как null |
ПолеtransformationCancelReason |
Битрикс24transformationCancelReason |
Типstring | null | ROда | ОписаниеПричина отмены преобразования в PDF. Пустая строка приходит как null |
ПолеpullTag |
Битрикс24pullTag |
Типstring | null | ROда | ОписаниеТег подписки на обновления статуса преобразования |
★ — поля templateId, providerClassName, value обязательны в теле запроса при создании документа.
Пример ответа
Показаны 9 из 29 полей. Полный список — в таблице выше.
{
"success": true,
"data": {
"fields": {
"id": { "type": "number", "readonly": true, "label": "ID", "description": "Уникальный числовой идентификатор сгенерированного документа." },
"title": { "type": "string", "readonly": false, "label": "Название", "description": "Название документа." },
"number": { "type": "string", "readonly": false, "label": "Номер", "description": "Номер документа, отображаемый в печатной форме." },
"templateId": { "type": "number", "readonly": false, "required": true, "label": "Шаблон", "description": "ID шаблона, по которому создаётся документ. Список: GET /v1/doc-templates." },
"providerClassName": { "type": "string", "readonly": false, "required": true, "label": "Провайдер данных", "description": "Имя класса провайдера данных, который поставляет значения для шаблона." },
"value": { "type": "string", "readonly": false, "required": true, "label": "Идентификатор владельца", "description": "Идентификатор сущности, по которой провайдер данных строит документ (например, ID сделки)." },
"createTime": { "type": "datetime", "readonly": true, "label": "Дата создания", "description": "Дата и время создания документа." },
"publicUrl": { "type": "string", "readonly": true, "label": "Публичная ссылка", "description": "Публичная ссылка для передачи документа." },
"transformationErrorCode": { "type": "string", "readonly": true, "nullable": true, "label": "Код ошибки преобразования в PDF", "description": "Код ошибки преобразования документа в PDF." }
},
"batch": ["create", "update", "delete"]
}
}
Пример ответа при ошибке
403 — у ключа нет нужного скоупа:
{
"success": false,
"error": {
"code": "SCOPE_DENIED",
"message": "This endpoint requires 'documentgenerator' scope"
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP403 | КодSCOPE_DENIED |
ОписаниеAPI-ключу не хватает скоупа documentgenerator |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP429 | КодRATE_LIMITED |
ОписаниеПревышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Действующее значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After |
Полный список общих ошибок API — Ошибки.