Для AI-агентов: markdown этой страницы — /docs-content/entities/doc-templates/create.md индекс документации — /llms.txt
Создать шаблон
POST /v1/doc-templates
Создаёт пригодный для генерации документов шаблон из файла .docx. Передайте ровно один источник: содержимое файла строкой base64 в file или ID объекта Диска в fileId. Платформа скачивает файл с Диска и импортирует его содержимое тем же способом, что и file.
Для обоих вариантов ключу нужен скоуп documentgenerator. Вариант с fileId дополнительно требует disk, потому что платформа читает объект Диска.
Поля запроса (body)
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
Полеname |
Типstring | Обяз.да | ОписаниеНазвание шаблона |
ПолеnumeratorId |
Типnumber | Обяз.да | ОписаниеИдентификатор нумератора |
Полеregion |
Типstring | Обяз.да | ОписаниеРегион, например ru |
Полеfile |
Типstring | Обяз.одно из двух | ОписаниеСодержимое файла .docx в виде строки base64. Достаточно скоупа documentgenerator |
ПолеfileId |
Типnumber | string | Обяз.одно из двух | ОписаниеПоложительный ID объекта Диска. Дополнительно нужен скоуп disk. Десятичная строка принимается для совместимости |
Полеcode |
Типstring | Обяз.нет | ОписаниеСимвольный код шаблона |
Полеactive |
Типstring | Обяз.нет | ОписаниеАктивность шаблона: "Y" или "N" |
ПолеwithStamps |
Типstring | Обяз.нет | ОписаниеИспользовать печати и подписи: "Y" или "N" |
Полеsort |
Типnumber | Обяз.нет | ОписаниеИндекс сортировки |
Полеusers |
Типarray | Обяз.нет | ОписаниеИдентификаторы сотрудников, которым доступен шаблон |
Примеры
curl — личный ключ
curl -X POST "https://vibecode.bitrix24.tech/v1/doc-templates" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Шаблон договора",
"numeratorId": 1,
"region": "ru",
"file": "<base64-содержимое .docx>"
}'
curl — OAuth-приложение
curl -X POST "https://vibecode.bitrix24.tech/v1/doc-templates" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Шаблон договора",
"numeratorId": 1,
"region": "ru",
"file": "<base64-содержимое .docx>"
}'
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/doc-templates', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Шаблон договора',
numeratorId: 1,
region: 'ru',
file: '<base64-содержимое .docx>',
}),
})
const { success, data } = await res.json()
console.log('ID шаблона:', data.id)
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/doc-templates', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Шаблон договора',
numeratorId: 1,
region: 'ru',
file: '<base64-содержимое .docx>',
}),
})
const { success, data } = await res.json()
Чтобы использовать файл с Диска, сначала загрузите .docx через POST /v1/files/upload, затем передайте полученный id в поле fileId вместо file в одном из примеров выше. Для такого запроса ключ должен содержать скоупы documentgenerator и disk.
Поля ответа
Статус ответа — 201.
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata |
Типobject | ОписаниеСозданный шаблон |
Полеdata.id |
Типnumber | ОписаниеИдентификатор созданного шаблона |
Полеdata.name |
Типstring | ОписаниеНазвание шаблона |
Полеdata.region |
Типstring | ОписаниеРегион |
Полеdata.code |
Типstring/null | ОписаниеСимвольный код шаблона. null, если не передан |
Полеdata.active |
Типstring | ОписаниеАктивность: "Y" или "N" |
Полеdata.moduleId |
Типstring | ОписаниеИдентификатор модуля-источника шаблона. У шаблонов этого раздела — rest |
Полеdata.numeratorId |
Типnumber | ОписаниеИдентификатор нумератора |
Полеdata.withStamps |
Типstring | ОписаниеИспользование печатей и подписей: "Y" или "N" |
Полеdata.providers |
Типobject | ОписаниеСопоставление поставщиков данных шаблона |
Полеdata.users |
Типobject | ОписаниеСопоставление идентификаторов пользователей, которым доступен шаблон |
Полеdata.isDeleted |
Типboolean | ОписаниеПомечен ли шаблон удалённым |
Полеdata.sort |
Типnumber | ОписаниеИндекс сортировки |
Полеdata.createTime |
Типstring | ОписаниеДата создания (ISO 8601) |
Полеdata.updateTime |
Типstring | ОписаниеДата последнего изменения (ISO 8601) |
Полеdata.timezone |
Типstring/null | ОписаниеЧасовой пояс шаблона. null, если не задан |
Полеdata.download |
Типstring | ОписаниеАдрес скачивания собранного документа из шаблона |
Полеdata.downloadMachine |
Типstring | ОписаниеАдрес скачивания файла шаблона через API Вайбкод — GET /v1/doc-templates/:id/download. Нужен X-Api-Key со скоупом documentgenerator |
Если в ответе есть fileId, это ID файла во внутреннем реестре Генератора документов, а не переданный ID объекта Диска. Не используйте его в эндпоинтах /v1/files.
Лимиты
- Максимальный размер JSON-тела — 3 МиБ.
- Максимальный размер
.docx— 2 МиБ после декодированияfileили скачиванияfileId. - При превышении любого из лимитов возвращается
413 PAYLOAD_TOO_LARGEдо создания шаблона.
Пример ответа
{
"success": true,
"data": {
"id": 209,
"name": "Шаблон договора",
"region": "ru",
"code": null,
"download": "/bitrix/services/main/ajax.php?action=documentgenerator.api.template.download&SITE_ID=s1&id=209",
"active": "Y",
"moduleId": "rest",
"numeratorId": 1,
"withStamps": "N",
"providers": {
"bitrix\\documentgenerator\\dataprovider\\rest": "bitrix\\documentgenerator\\dataprovider\\rest"
},
"users": {
"U1": "U1"
},
"isDeleted": false,
"sort": 500,
"createTime": "2026-05-12T09:03:38.000Z",
"updateTime": "2026-05-12T09:03:38.000Z",
"timezone": null,
"downloadMachine": "https://vibecode.bitrix24.tech/v1/doc-templates/209/download"
}
}
Пример ответа при ошибке
400 — не передан файл:
{
"success": false,
"error": {
"code": "MISSING_FILE_OR_FILE_ID",
"message": "POST /v1/doc-templates requires exactly one source: \"file\" with base64-encoded .docx content, or \"fileId\" with a Disk object ID (requires disk scope)."
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодMISSING_FILE_OR_FILE_ID |
ОписаниеНе передан ни file, ни fileId |
| HTTP400 | КодCONFLICTING_FILE_FIELDS |
ОписаниеПереданы и file, и fileId |
| HTTP400 | КодMISSING_REQUIRED_FIELD |
ОписаниеОтсутствует name, numeratorId или region |
| HTTP400 | КодINVALID_PARAMS |
Описаниеname/region не строка, numeratorId не положительное целое либо fileId не является положительным безопасным целым ID |
| HTTP400 | КодREADONLY_FIELD |
ОписаниеВ теле передано поле только для чтения — например модуль-владелец moduleId, который проставляет платформа |
| HTTP415 | КодUNSUPPORTED_MEDIA_TYPE |
ОписаниеЗапрос отправлен с multipart/form-data |
| HTTP413 | КодPAYLOAD_TOO_LARGE |
ОписаниеJSON-тело больше 3 МиБ либо файл после декодирования/скачивания больше 2 МиБ |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеКлючу не хватает documentgenerator либо для варианта с fileId дополнительного скоупа disk |
| HTTP404 | КодDOWNLOAD_URL_NOT_FOUND |
ОписаниеДля объекта Диска не получен адрес скачивания |
| HTTP502 | КодDOWNLOAD_FAILED |
ОписаниеСкачать файл с Диска не удалось. Ответ не раскрывает адрес скачивания и текст сетевой ошибки |
| HTTP401 | КодTOKEN_MISSING |
ОписаниеУ ключа нет настроенных токенов |
Полный список общих ошибок API — Ошибки.