Для 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 — личный ключ

Terminal
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-приложение

Terminal
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 — личный ключ

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-приложение

javascript
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 до создания шаблона.

Пример ответа

JSON
{
  "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 — не передан файл:

JSON
{
  "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 — Ошибки.

Смотрите также