لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/doc-templates.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Document templates

A document template is a .docx file with placeholders that Bitrix24 fills in with real values to produce ready-to-use documents.

Bitrix24 API: documentgenerator.template.* Scope: documentgenerator; creation from fileId additionally requires disk

CRM templates live in their own section and require crm; this section covers app templates (moduleId: rest).

Create template

POST /v1/doc-templates

Creates a renderable document template from a .docx file. Pass exactly one source: the file content as a base64 string in file, or a Disk object ID in fileId. The platform downloads the Disk file and imports its content through the same path as file.

Both variants require the documentgenerator scope. The fileId variant additionally requires disk because the platform reads the Disk object.

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionTemplate name
FieldnumeratorId Typenumber Requiredyes DescriptionNumerator identifier
Fieldregion Typestring Requiredyes DescriptionRegion, for example uk
Fieldfile Typestring Requiredone of two Description.docx file content as a base64 string. Requires only documentgenerator
FieldfileId Typenumber | string Requiredone of two DescriptionPositive Disk object ID. Additionally requires disk; a decimal string is accepted for compatibility
Fieldcode Typestring Requiredno DescriptionSymbolic code of the template
Fieldactive Typestring Requiredno DescriptionWhether the template is active: "Y" or "N"
FieldwithStamps Typestring Requiredno DescriptionWhether to use stamps and signatures: "Y" or "N"
Fieldsort Typenumber Requiredno DescriptionSort index
Fieldusers Typearray Requiredno DescriptionIdentifiers of employees who have access to the template

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/doc-templates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract template",
    "numeratorId": 1,
    "region": "uk",
    "file": "<base64 .docx content>"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/doc-templates" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract template",
    "numeratorId": 1,
    "region": "uk",
    "file": "<base64 .docx content>"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/doc-templates', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Contract template',
    numeratorId: 1,
    region: 'uk',
    file: '<base64 .docx content>',
  }),
})

const { success, data } = await res.json()
console.log('Template ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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: 'Contract template',
    numeratorId: 1,
    region: 'uk',
    file: '<base64 .docx content>',
  }),
})

const { success, data } = await res.json()

To use a file from Disk, first upload the .docx through POST /v1/files/upload, then pass the returned id in fileId instead of file in one of the examples above. Such a request requires both the documentgenerator and disk scopes on the key.

Response fields

Returns the full object of the created template. Response status — 201.

Field Type Description
Fieldid Typenumber DescriptionIdentifier of the created template
Fieldname Typestring DescriptionTemplate name
Fieldregion Typestring DescriptionRegion
Fieldcode Typestring DescriptionSymbolic code of the template
Fieldactive Typestring DescriptionWhether the template is active: "Y" or "N"
FieldmoduleId Typestring DescriptionIdentifier of the template's source module
FieldnumeratorId Typenumber DescriptionNumerator identifier
FieldwithStamps Typestring DescriptionUse of stamps and signatures: "Y" or "N"
Fieldproviders Typeobject DescriptionMapping of the template's data providers
Fieldusers Typeobject DescriptionMapping of user identifiers with access to the template
FieldisDeleted Typeboolean DescriptionWhether the template is marked as deleted
Fieldsort Typenumber DescriptionSort index
FieldcreateTime Typestring DescriptionCreation date (ISO 8601)
FieldupdateTime Typestring DescriptionLast update date (ISO 8601)
Fielddownload Typestring DescriptionDownload URL of the document built from the template
FielddownloadMachine Typestring DescriptionVibe API URL for a REST template; requires X-Api-Key with documentgenerator scope. Absent for other modules.

If the response contains fileId, it is a file ID from the internal Document Generator registry, not the Disk object ID supplied in the request. Do not use it with /v1/files endpoints.

Limits

  • The JSON body may be up to 3 MiB.
  • The .docx may be up to 2 MiB after decoding file or downloading fileId.
  • Exceeding either limit returns 413 PAYLOAD_TOO_LARGE before a template is created.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 209,
    "name": "Contract template",
    "region": "uk",
    "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",
    "downloadMachine": "https://vibecode.bitrix24.com/v1/doc-templates/209/download"
  }
}

Error response example

400 — no file passed:

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)."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_FILE_OR_FILE_ID DescriptionNeither file nor fileId was passed
HTTP400 CodeCONFLICTING_FILE_FIELDS DescriptionBoth file and fileId were passed
HTTP400 CodeMISSING_REQUIRED_FIELD Descriptionname, numeratorId, or region is missing
HTTP400 CodeINVALID_PARAMS Descriptionname/region is not a string, numeratorId is not a positive integer, or fileId is not a positive safe integer ID
HTTP400 CodeREADONLY_FIELD DescriptionThe body carried a read-only field — for example the owner module moduleId, which the platform assigns
HTTP415 CodeUNSUPPORTED_MEDIA_TYPE DescriptionRequest sent with multipart/form-data
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionThe JSON body exceeds 3 MiB or the decoded/downloaded file exceeds 2 MiB
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks documentgenerator, or the fileId variant lacks the additional disk scope
HTTP404 CodeDOWNLOAD_URL_NOT_FOUND DescriptionBitrix24 returned no download address for the Disk object
HTTP502 CodeDOWNLOAD_FAILED DescriptionThe Disk file could not be downloaded; the response does not expose the download address or network error text
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens

Full list of common API errors — Errors.

See also