Для AI-агентов: markdown этой страницы — /docs-content/entities/doc-templates/fields.md индекс документации — /llms.txt
Поля шаблона
GET /v1/doc-templates/fields
Возвращает полную схему полей шаблона документа: имя поля, тип, признак «только для чтения» и обязательность при создании. Поля помечены ★ — обязательны в теле запроса при создании шаблона.
Примеры
curl — личный ключ
curl "https://vibecode.bitrix24.tech/v1/doc-templates/fields" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl "https://vibecode.bitrix24.tech/v1/doc-templates/fields" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/doc-templates/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/doc-templates/fields', {
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
},
})
const { success, data } = await res.json()
Поля ответа
Подписи полей label и description приходят на русском языке. Заголовками запроса язык не переключается.
Колонка типа и значения type из ответа этого эндпоинта описывают канонические сохранённые значения и поля ответа. Варианты ввода только для создания приведены на странице Создание шаблона: в частности, POST /v1/doc-templates принимает fileId и как положительную десятичную строку, а в ответе это поле остаётся числом.
| Поле | Битрикс24 | Тип | RO | Описание |
|---|---|---|---|---|
Полеid |
Битрикс24id |
Типnumber | ROда | ОписаниеID шаблона |
Полеname |
Битрикс24name |
Типstring | RO | Описание★ Название шаблона |
ПолеnumeratorId |
Битрикс24numeratorId |
Типnumber | RO | Описание★ ID нумератора, который присваивает документам порядковые номера |
Полеregion |
Битрикс24region |
Типstring | RO | Описание★ Код региона шаблона, например ru или by |
Полеcode |
Битрикс24code |
Типstring | null | RO | ОписаниеСистемный код шаблона для привязки в коде приложения. null, если код не задан |
ПолеmoduleId |
Битрикс24moduleId |
Типstring | ROда | ОписаниеИдентификатор модуля-владельца шаблона. Битрикс24 всегда проставляет rest для шаблонов, созданных через REST API |
Полеactive |
Битрикс24active |
Типstring | RO | ОписаниеДоступность шаблона: Y — включён, N — выключен |
ПолеbodyType |
Битрикс24bodyType |
Типstring | RO | ОписаниеФормат тела документа, например DOCX |
ПолеwithStamps |
Битрикс24withStamps |
Типstring | RO | ОписаниеПечать факсимиле и штампов: Y — добавляются, N — нет |
Полеsort |
Битрикс24sort |
Типnumber | RO | ОписаниеПорядок шаблона в списке: чем меньше значение, тем выше |
Полеusers |
Битрикс24users |
Типarray | RO | ОписаниеИдентификаторы сотрудников, которым доступен шаблон. Список: GET /v1/users |
ПолеfileId |
Битрикс24fileId |
Типnumber | RO | ОписаниеВ запросе создания — ID объекта Диска, содержимое которого платформа импортирует. В запросе обновления не применяется. В ответе — ID из отдельного реестра Генератора документов, не ID объекта Диска |
Полеfile |
Битрикс24file |
Типstring | RO | ОписаниеСодержимое .docx в base64. При создании передаётся ровно одно из полей file и fileId. При обновлении заменяет файл шаблона |
ПолеcreatedBy |
Битрикс24createdBy |
Типnumber | ROда | ОписаниеИдентификатор создавшего сотрудника |
ПолеupdatedBy |
Битрикс24updatedBy |
Типnumber | null | ROда | ОписаниеИдентификатор изменившего сотрудника. null, если шаблон не изменялся |
ПолеisDeleted |
Битрикс24isDeleted |
Типboolean | ROда | ОписаниеШаблон помечен как удалённый |
ПолеcreateTime |
Битрикс24createTime |
Типdatetime | ROда | ОписаниеДата создания |
ПолеupdateTime |
Битрикс24updateTime |
Типdatetime | ROда | ОписаниеДата изменения |
Полеdownload |
Битрикс24download |
Типstring | ROда | ОписаниеСсылка для скачивания исходного файла шаблона |
ПолеdownloadMachine |
Битрикс24downloadMachine |
Типstring | ROда | ОписаниеАдрес Vibe API; нужен X-Api-Key со скоупом documentgenerator |
Полеproviders |
Битрикс24providers |
Типobject | ROда | ОписаниеПеречень доступных поставщиков хранилищ с их настройками |
ПолеisDefault |
Битрикс24isDefault |
Типstring | ROда | ОписаниеПризнак того, что шаблон используется по умолчанию |
ПолеproductsTableVariant |
Битрикс24productsTableVariant |
Типstring | ROда | ОписаниеВариант оформления таблицы товаров в генерируемом документе |
★ — поля name, numeratorId, region обязательны в теле запроса при создании шаблона.
При POST /v1/doc-templates поле fileId требует скоупы documentgenerator и disk; поле file требует только documentgenerator. Максимальный размер файла — 2 МиБ после декодирования или скачивания, максимальный размер JSON-тела — 3 МиБ. Это правило относится к созданию и не меняет контракт PATCH /v1/doc-templates/:id.
Пример ответа
{
"success": true,
"data": {
"fields": {
"id": { "type": "number", "readonly": true, "label": "ID шаблона", "description": "Уникальный идентификатор шаблона документа." },
"name": { "type": "string", "readonly": false, "required": true, "label": "Название шаблона", "description": "Название шаблона документа, отображаемое пользователю." },
"numeratorId": { "type": "number", "readonly": false, "required": true, "label": "ID нумератора", "description": "Идентификатор нумератора, присваивающего документам порядковые номера." },
"region": { "type": "string", "readonly": false, "required": true, "label": "Регион шаблона", "description": "Код региона шаблона, например ru или by." },
"code": { "type": "string", "readonly": false, "label": "Системный код", "description": "Системный код шаблона для привязки к нему в коде приложения." },
"moduleId": { "type": "string", "readonly": true, "label": "ID модуля-владельца", "description": "Идентификатор модуля Битрикс24, которому принадлежит шаблон. Назначается сервером." },
"active": { "type": "string", "readonly": false, "label": "Активность", "description": "Признак доступности шаблона: включён или выключен." },
"bodyType": { "type": "string", "readonly": false, "label": "Формат тела", "description": "Формат содержимого генерируемого документа, например DOCX." },
"withStamps": { "type": "string", "readonly": false, "label": "Печать штампов", "description": "Признак добавления факсимиле и штампов при генерации документа." },
"sort": { "type": "number", "readonly": false, "label": "Сортировка", "description": "Значение для сортировки шаблона в списке: чем меньше, тем выше." },
"users": { "type": "array", "readonly": false, "label": "Доступные сотрудники", "description": "Список идентификаторов сотрудников, которым доступен шаблон." },
"fileId": { "type": "number", "readonly": false, "label": "ID файла на Диске", "description": "В POST /v1/doc-templates — ID объекта Диска, содержимое которого платформа импортирует в Генератор документов. fileId в ответе с шаблоном относится к отдельному реестру файлов Генератора документов, его нельзя использовать в эндпоинтах /v1/files." },
"file": { "type": "string", "readonly": false, "label": "Содержимое файла", "description": "Содержимое файла шаблона в формате .docx, закодированное в base64." },
"createdBy": { "type": "number", "readonly": true, "label": "Создал сотрудник", "description": "Идентификатор сотрудника, создавшего шаблон." },
"updatedBy": { "type": "number", "readonly": true, "label": "Изменил сотрудник", "description": "Идентификатор сотрудника, последним изменившего шаблон." },
"isDeleted": { "type": "boolean", "readonly": true, "label": "Удалён", "description": "Признак того, что шаблон помечен как удалённый." },
"createTime": { "type": "datetime", "readonly": true, "label": "Дата создания", "description": "Дата и время создания шаблона." },
"updateTime": { "type": "datetime", "readonly": true, "label": "Дата изменения", "description": "Дата и время последнего изменения шаблона." },
"download": { "type": "string", "readonly": true, "label": "Ссылка на скачивание", "description": "Ссылка для скачивания исходного файла шаблона." },
"downloadMachine": { "type": "string", "readonly": true, "label": "Машинная ссылка", "description": "Адрес Vibe API; нужен X-Api-Key со скоупом documentgenerator." },
"providers": { "type": "object", "readonly": true, "label": "Список поставщиков", "description": "Перечень доступных поставщиков хранилищ файла шаблона с их настройками." },
"isDefault": { "type": "string", "readonly": true, "label": "Шаблон по умолчанию", "description": "Признак того, что шаблон используется по умолчанию." },
"productsTableVariant": { "type": "string", "readonly": true, "label": "Вариант таблицы товаров", "description": "Вариант оформления таблицы товаров в генерируемом документе." }
}
}
}
Пример ответа при ошибке
403 — у ключа нет нужного скоупа:
{
"success": false,
"error": {
"code": "SCOPE_DENIED",
"message": "This endpoint requires 'documentgenerator' scope"
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP403 | КодSCOPE_DENIED |
ОписаниеAPI-ключу не хватает скоупа documentgenerator |
| HTTP401 | КодTOKEN_MISSING |
Описаниеу ключа нет настроенных токенов |
| HTTP429 | КодRATE_LIMITED |
ОписаниеПревышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Действующее значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After |
Полный список общих ошибок API — Ошибки.