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

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

CRM document templates

A CRM document template is a .docx file with placeholder tags that Bitrix24 uses to generate documents for deals, contacts, companies and other CRM records.

Bitrix24 API: crm.documentgenerator.template.* Scope: crm

Create a CRM document template

POST /v1/crm-document-templates

Creates a CRM document template from a .docx file passed as a base64 string and binds it to CRM record types. Fields go in the JSON root without a wrapper.

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionTemplate name
Fieldfile Typestring Requiredyes DescriptionContents of your .docx file as a base64 string, no more than 2 MiB after decoding. See "Known specifics" for how to get the string
FieldnumeratorId Typenumber Requiredyes DescriptionID of the numerator that assigns numbers to documents. A positive integer. The list of numerators is not exposed through /v1/...
Fieldregion Typestring Requiredyes DescriptionTemplate region, for example uk
FieldentityTypeId Typearray Requiredyes DescriptionNon-empty array of CRM record types, numbers or strings: 2 — deal, 3 — contact, 4 — company. Smart process types — GET /v1/smart-processes
Fieldusers Typearray Requiredno DescriptionArray of access codes as strings: UA — all employees, U<id> — the employee with this ID from GET /v1/users. When called with a personal key without this field, the template is available only to the key owner: the response returns that employee's U<id>
Fieldactive Typestring Requiredno DescriptionWhether the template is active: Y or N. Defaults to Y
FieldwithStamps Typestring Requiredno DescriptionStamps and signatures in documents: Y or N. Defaults to N
Fieldsort Typenumber Requiredno DescriptionSort index. Defaults to 500
Fieldcode Typestring Requiredno DescriptionTemplate symbolic code

The fields id, fileId, moduleId, download, downloadMachine, isDeleted, isDefault, createTime, updateTime, createdBy, updatedBy, providers are read-only. A request with any of them is rejected with 400 READONLY_FIELD. The name is compared ignoring case and underscores: module_id and ModuleId are rejected too.

Examples

In the examples, contract.docx is your template file. The request body is assembled into the template.json file and then sent.

curl — personal key

Terminal 
printf '{"name":"Supply agreement","numeratorId":1,"region":"uk","entityTypeId":[2],"users":["UA"],"file":"%s"}' \
  "$(base64 < contract.docx | tr -d '\n')" > template.json

curl -X POST "https://vibecode.bitrix24.com/v1/crm-document-templates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @template.json

curl — OAuth application

Terminal 
printf '{"name":"Supply agreement","numeratorId":1,"region":"uk","entityTypeId":[2],"users":["UA"],"file":"%s"}' \
  "$(base64 < contract.docx | tr -d '\n')" > template.json

curl -X POST "https://vibecode.bitrix24.com/v1/crm-document-templates" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @template.json

JavaScript — personal key

javascript 
import { readFile } from 'node:fs/promises'

const file = (await readFile('contract.docx')).toString('base64')

const res = await fetch('https://vibecode.bitrix24.com/v1/crm-document-templates', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Supply agreement',
    numeratorId: 1,
    region: 'uk',
    entityTypeId: [2],
    users: ['UA'],
    file,
  }),
})

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

JavaScript — OAuth application

javascript 
import { readFile } from 'node:fs/promises'

const file = (await readFile('contract.docx')).toString('base64')

const res = await fetch('https://vibecode.bitrix24.com/v1/crm-document-templates', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Supply agreement',
    numeratorId: 1,
    region: 'uk',
    entityTypeId: [2],
    users: ['UA'],
    file,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created template
Fielddata.id Typestring DescriptionTemplate ID, as a string
Fielddata.name Typestring DescriptionTemplate name
Fielddata.region Typestring DescriptionTemplate region
Fielddata.code Typestring | null DescriptionTemplate symbolic code, null — no code set
Fielddata.download Typestring DescriptionTemplate file download URL in the Bitrix24 web interface. To download through the API, use downloadMachine
Fielddata.active Typestring DescriptionWhether the template is active: Y or N
Fielddata.moduleId Typestring DescriptionOwner module, always crm
Fielddata.numeratorId Typestring DescriptionNumerator ID, as a string
Fielddata.withStamps Typestring DescriptionStamps and signatures: Y or N
Fielddata.users Typeobject DescriptionAccess codes as an object, each code serves as both key and value: {"UA": "UA"}
Fielddata.isDeleted Typestring DescriptionDeletion flag: N for an active template
Fielddata.sort Typestring DescriptionSort index, as a string
Fielddata.createTime Typestring DescriptionCreation date in ISO 8601 with a time zone offset
Fielddata.updateTime Typestring DescriptionLast modification date in ISO 8601 with a time zone offset
Fielddata.entityTypeId Typearray DescriptionCRM record types as strings, exactly as passed in the request. When the template is read, the deal type expands by funnel — see What to know before you start
Fielddata.downloadMachine Typestring Description.docx download URL through the Vibecode API — GET /v1/crm-document-templates/:id/download

Response example

HTTP 201:

JSON 
{
  "success": true,
  "data": {
    "id": "263",
    "name": "Supply agreement",
    "region": "uk",
    "code": null,
    "download": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=crm.documentgenerator.template.download&SITE_ID=s1&id=263",
    "active": "Y",
    "moduleId": "crm",
    "numeratorId": "1",
    "withStamps": "N",
    "users": {
      "UA": "UA"
    },
    "isDeleted": "N",
    "sort": "500",
    "createTime": "2026-10-08T13:20:29+00:00",
    "updateTime": "2026-10-08T13:20:29+00:00",
    "entityTypeId": ["2"],
    "downloadMachine": "https://vibecode.bitrix24.com/v1/crm-document-templates/263/download"
  }
}

Error response example

400 — a required field is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Required field 'numeratorId' is missing."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionOne of the required fields is missing, or its value is null, an empty string or an empty array. An empty body {} gets the same code
HTTP400 CodeINVALID_PARAMS Descriptionfile is not a base64 string. A placeholder instead of the file contents is rejected with this code before the request reaches Bitrix24
HTTP400 CodeINVALID_PARAMS Descriptionusers is not an array of non-empty strings, for example, the {"UA": "UA"} object was passed in the shape the response returns
HTTP400 CodeINVALID_PARAMS DescriptionentityTypeId is not an array, or it contains a value that is neither a positive number nor a non-empty string
HTTP400 CodeINVALID_PARAMS Descriptionname or region is not a string, numeratorId is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not a JSON object
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a read-only field, for example moduleId or fileId
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionThe file exceeds 2 MiB after decoding file, or the JSON body exceeds 3 MiB
HTTP429 CodeLARGE_BODY_BACKEND_BUSY DescriptionThe body exceeds 1 MiB and the platform is already processing the maximum volume of large bodies. Retry after Retry-After seconds
HTTP422 CodeBITRIX_WRITE_NOT_APPLIED DescriptionThe template was created, but Bitrix24 did not save all of the passed entityTypeId or users. The created template ID is in error.details.createdTemplateId. Check the template with GET /v1/crm-document-templates/:id before retrying: a repeated request creates another template
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the creation. The reason text is in error.message
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key works in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionBitrix24 rate-limited requests to the portal. Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

Known specifics

How to get the file value. Build the base64 string from your file with base64 < contract.docx | tr -d '\n', on macOS — base64 -i contract.docx | tr -d '\n'. Removing line breaks from the output is mandatory: a string with line breaks fails the base64 check.

See also