Para agentes de IA: markdown desta página — /docs-content-en/entities/doc-templates.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

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

Create template

POST /v1/doc-templates

Creates a document template from a .docx file. The file is passed in one of two ways:

  • file — .docx content as a base64 string.
  • fileId — the identifier of a file uploaded to Drive in advance.

Request fields (body)

Field Type Req. Description
name string yes Template name
numeratorId number yes Numerator identifier
region string yes Region, for example uk
file string * .docx file content as a base64 string. Alternative to the fileId field
fileId number * Drive file identifier. Source: upload via POST /v1/files/upload. Alternative to the file field
code string no Symbolic code of the template
active string no Whether the template is active: "Y" or "N"
withStamps string no Use stamps and signatures: "Y" or "N"
sort number no Sort index
users array no Identifiers of employees who have access to the template

* The file and fileId fields are mutually exclusive: pass exactly one of them.

To obtain fileId, upload the .docx file via POST /v1/files/upload — use the id value from the response as fileId.

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",
    "fileId": 9175
  }'

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",
    "fileId": 9175
  }'

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',
    fileId: 9175,
  }),
})

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',
    fileId: 9175,
  }),
})

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

Alternative — pass the .docx file content directly in the file field (base64):

JSON 
{
  "name": "Contract template",
  "numeratorId": 1,
  "region": "uk",
  "file": "<base64 .docx content>"
}

Response fields

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

Field Type Description
id number Identifier of the created template
name string Template name
region string Region
code string Symbolic code of the template
active string Whether the template is active: "Y" or "N"
moduleId string Identifier of the template's source module
numeratorId number Numerator identifier
withStamps string Use of stamps and signatures: "Y" or "N"
providers object Mapping of the template's data providers
users object Mapping of user identifiers with access to the template
isDeleted boolean Whether the template is marked as deleted
sort number Sort index
createTime string Creation date (ISO 8601)
updateTime string Last update date (ISO 8601)
download string Download URL of the document built from the template
downloadMachine string Download URL with a token for programmatic access

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://<portal>/rest/1/<token>/documentgenerator.api.template.download/?token=<token>"
  }
}

Error response example

400 — no file passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_FILE_OR_FILE_ID",
    "message": "POST /v1/doc-templates requires either \"file\" (base64-encoded .docx content) or \"fileId\" (Disk file ID). Neither was provided."
  }
}

Errors

HTTP Code Description
400 MISSING_FILE_OR_FILE_ID Neither file nor fileId was passed
400 CONFLICTING_FILE_FIELDS Both file and fileId were passed
400 MISSING_REQUIRED_FIELD name, numeratorId, or region is missing
400 INVALID_PARAMS name/region is not a string, or numeratorId is not a positive integer
400 READONLY_FIELD The body carried a read-only field — for example the owner module moduleId, which the platform assigns
415 UNSUPPORTED_MEDIA_TYPE Request sent with multipart/form-data
413 PAYLOAD_TOO_LARGE The multipart/form-data request body contains data
403 SCOPE_DENIED The key lacks the documentgenerator scope
401 TOKEN_MISSING The key has no configured tokens

Full list of common API errors — Errors.

See also