Для 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 — поле нельзя передать при создании и обновлении), label (отображаемое название) и description (краткое описание). Значения label/description локализованы: по-русски на .tech, по-английски на .com.

Поле Битрикс24 Тип RO Описание
id id number да Идентификатор документа
title title string Название документа
number number string Номер документа
templateId templateId number ★ Идентификатор шаблона. Список: GET /v1/doc-templates
providerClassName providerClassName string ★ Класс провайдера данных, например Bitrix\DocumentGenerator\DataProvider\Rest
value value string ★ Внешний идентификатор объекта-источника, из которого подставляются данные
values values object Значения полей-меток шаблона
fields fields object Описание форматирования полей
createTime createTime datetime да Дата создания
updateTime updateTime datetime да Дата последнего изменения
fileId fileId number Идентификатор файла DOCX
pdfId pdfId number Идентификатор файла PDF
imageId imageId number Идентификатор файла изображения
stampsEnabled stampsEnabled boolean Включены ли печати и подписи
provider provider string да Класс провайдера данных документа
downloadUrl downloadUrl string да Ссылка на скачивание DOCX для пользователя
pdfUrl pdfUrl string да Ссылка на скачивание PDF для пользователя
imageUrl imageUrl string да Ссылка на изображение для пользователя
downloadUrlMachine downloadUrlMachine string да Ссылка на скачивание DOCX для приложения
pdfUrlMachine pdfUrlMachine string да Ссылка на скачивание PDF для приложения
imageUrlMachine imageUrlMachine string да Ссылка на изображение для приложения
createdBy createdBy number да Идентификатор создавшего пользователя. Список: GET /v1/users
updatedBy updatedBy number | null да Идентификатор изменившего пользователя. null, если документ не изменялся. Список: GET /v1/users
publicUrl publicUrl string | null да Публичная ссылка на документ. null, если публичная ссылка не сформирована

★ — поля templateId, providerClassName, value обязательны в теле запроса при создании документа.

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

Показаны 8 из 24 полей. Полный список — в таблице выше.

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": "Публичная ссылка для передачи документа." }
    },
    "batch": ["create", "update", "delete"]
  }
}

Поле batch перечисляет операции документа, доступные в пакетном запросе.

Пример ответа при ошибке

403 — у ключа нет нужного скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'documentgenerator' scope"
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключу не хватает скоупа documentgenerator
401 MISSING_API_KEY Не передан заголовок X-Api-Key

Полный список общих ошибок API — Ошибки.

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