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

Поля документа

GET /v1/documents/fields

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

Примеры

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

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

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

Terminal
curl "https://vibecode.bitrix24.tech/v1/documents/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/documents/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/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 полей. Полный список — в таблице выше.

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

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

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