Для AI-агентов: markdown этой страницы — /docs-content/entities/doc-templates/fields.md индекс документации — /llms.txt

Поля шаблона

GET /v1/doc-templates/fields

Возвращает полную схему полей шаблона документа: имя поля, тип, признак «только для чтения» и обязательность при создании. Поля помечены ★ — обязательны в теле запроса при создании шаблона.

Примеры

curl — личный ключ

Terminal
curl "https://vibecode.bitrix24.tech/v1/doc-templates/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal
curl "https://vibecode.bitrix24.tech/v1/doc-templates/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

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

javascript
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.

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

JSON
{
  "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 — у ключа нет нужного скоупа:

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

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