Эффективная интеграция и кастомизация функционала в Битрикс24 часто требует работы на уровне API. Сегодня мы подробно рассмотрим «Как добавить шаблон и создать документ на его основе». Вы узнаете экспертные методики работы с добавить шаблон и научитесь избегать типичных ошибок начинающих разработчиков.

Как добавить шаблон и создать документ на его основе

> Scope: crm
>
> Кто может выполнять метод: пользователи с административным доступом к разделу CRM

Автоматизировать работу с документами в CRM можно с помощью скрипта. Он будет выполнять полный цикл генерации документа: создавать нумератор, загружать шаблон в формате .docx и формировать документ по конкретной сделке.

Чтобы создать документ, последовательно выполним методы:

1. crm.documentgenerator.numerator.add — создадим нумератор документа,

2. crm.documentgenerator.template.add — загрузим шаблон документа,

3. crm.documentgenerator.document.add — сгенерируем документ.

Подготовим переменные

Определим основные переменные, которые будем использовать в процессе генерации документа.

filePath — путь к файлу шаблона. Укажем template.docx.

iDealID — идентификатор сделки. Создадим документ для сделки с идентификатором 1.

sDocName — имя создаваемого документа. Укажем Демонстрационная реализация товара.

   let filePath = 'template.docx'; 
   let iDealID = 1; 
   let sDocName = 'Демонстрационная реализация товара';

   $filePath = __DIR__ . '/template.docx';  
   $iDealID = 1;  
   $sDocName = 'Демонстрационная реализация товара';

1\. Создадим нумератор документа

Создадим нумератор для документов с помощью crm.documentgenerator.numerator.add. В метод передадим два параметра.

name — название нумератора. Укажем Rest Numerator.

template — шаблон, по которому будет генерироваться номер документа. Укажем {NUMBER} — это переменная, которая будет заменена на порядковый номер. Можно использовать другие переменные, например, {DAY} —текущий день, {CLIENT_ID} — идентификатор клиента, {RANDOM} — случайный номер.

   BX24.callMethod(
       'crm.documentgenerator.numerator.add',
       {
           'fields': {
               'name': 'Нумератор из REST',
               'template': '{NUMBER}'
           }
       },
       function(resNum) {
           if (resNum.error()) {
               console.error(resNum.error());
               alert('Нумератор не добавлен: ' + resNum.error_description());
               return;
           }
       }
   );

   $resNum = CRest::call(
       'crm.documentgenerator.numerator.add',
       [
           'fields' => [
               'name' => 'Нумератор из REST',
               'template' => '{NUMBER}',
           ]
       ]
   );

Метод crm.documentgenerator.numerator.add вернет объект resNum с информацией о созданном нумераторе.

"numerator":{
    "name":"Нумератор из REST",
    "template":"{NUMBER}",
    "id":43,
    "code":null,
    "settings":{
        "Bitrix_Main_Numerator_Generator_SequentNumberGenerator":{
            "start":1,
            "step":1,
            "length":0,
            "padString":"0",
            "periodicBy":null,
            "timezone":null,
            "isDirectNumeration":false
        }
    }
}

2\. Загрузим шаблон документа

Если нумератор создан, добавим шаблон документа с помощью метода crm.documentgenerator.template.add.

Содержимое файла шаблона нужно преобразовать в формат Base64.

В crm.documentgenerator.template.add нужно передать следующие данные:

name — название шаблона. Укажем переменную sDocName.

numeratorId — идентификатор нумератора. Передадим его из объекта resNum, который получен на первом шаге.

region — регион шаблона. Влияет на локализацию, например, валюту и дату. Укажем ru — Россия.

users — массив прав доступа. Определяет, какие группы пользователей могут видеть и использовать шаблон. Укажем UA — все авторизованные пользователи.

entityTypeId — идентификатор типа объекта CRM. Укажем 2 — сделка. Полный список типов объектов можно получить с помощью метода crm.enum.ownertype.

file — контент файла filePath, который преобразован в формат Base64.

   function fileToBase64(filePath) {
       return new Promise((resolve, reject) => {
           fetch(filePath)
               .then(response => response.blob())
               .then(blob => {
                   let reader = new FileReader();
                   reader.onloadend = () => resolve(reader.result.split(',')[1]);
                   reader.onerror = reject;
                   reader.readAsDataURL(blob);
               });
       });
   }
   
   let fileContent = await fileToBase64(filePath);
   
   BX24.callMethod(
       'crm.documentgenerator.template.add',
       {
           'fields': {
               'name': sDocName,
               'numeratorId': resNum.data().numerator.id,
               'region': 'ru',
               'users': ['UA'],
               'entityTypeId': ['2'],
               'file': fileContent
           }
       },
       function(resTemplate) {
           if (resTemplate.error()) {
               console.error(resTemplate.error());
               alert('Шаблон не добавлен: ' + resTemplate.error_description());
               return;
           }
       }
   );

   $resTemplate = CRest::call(
       'crm.documentgenerator.template.add',
       [
           'fields' => [
               'name' => $sDocName,
               'numeratorId' => $resNum['result']['numerator']['id'],  
               'region' => 'ru', 
               'users' => [
                   'UA'//User All
               ],
               'entityTypeId' => ['2'], 
               'file' => base64_encode(file_get_contents($filePath))
           ]
       ]
   );

Метод crm.documentgenerator.template.add вернет объект resTemplate с информацией о шаблоне.

template: { 
    "id": "39", 
    "name": "Демонстрационная реализация товара", 
    "region": "ru",
    "active": "Y",
    "code": null,
    "createTime": "2025-07-09T16:12:13+03:00",
    "download": "https://some-domain.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.template.download&SITE_ID=s1&id=39",
    "downloadMachine": "https://some-domain.bitrix24.ru/rest/crm.documentgenerator.template.download.json?sessid=c4ad892d7583ead4fd38666a0af85cb7&token=crm%7CYWN0aW9uPWNybS5kb2N1bWVudGdlbmVyYXRvci50ZW1wbGF0ZS5kb3dubG9hZCZTSVRFX0lEPXMxJmlkPTM5Jl89azNRNlFuVVRvUGl5VzNLaExTVDJCR3g1WjdyQ0tSSFA%3D%7CImNybS5kb2N1bWVudGdlbmVyYXRvci50ZW1wbGF0ZS5kb3dubG9hZHxjcm18WVdOMGFXOXVQV055YlM1a2IyTjFiV1Z1ZEdkbGJtVnlZWFJ2Y2k1MFpXMXdiR0YwWlM1a2IzZHViRzloWkNaVFNWUkZYMGxFUFhNeEptbGtQVE01Smw4OWF6TlJObEZ1VlZSdlVHbDVWek5MYUV4VFZESkNSM2cxV2pkeVEwdFNTRkE9fGM0YWQ4OTJkNzU4M2VhZDRmZDM4NjY2YTBhZjg1Y2I3Ig%3D%3D.GMgjAbCT099xlo8CJN9n5mP2s7MBbqfU%2BbEM%2FAzpoYE%3D",
    "entityTypeId": [ "0": "2" ],
    "length": 1,
    "numeratorId": "43",
    "users": [ "0": "UA" ],
    "sort": 500
}

3\. Сгенерируем документ

Если шаблон успешно загружен, создадим документ для сделки с помощью метода crm.documentgenerator.document.add. В методе укажем три параметра.

1. templateId — идентификатор шаблона. Передадим его из объекта resTemplate, который получен на втором шаге.

2. entityTypeId — идентификатор типа объекта CRM. Укажем 2 — сделка. Полный список типов объектов можно получить с помощью метода crm.enum.ownertype.

3. entityId — идентификатор сделки. Укажем переменную iDealID.

   BX24.callMethod(
       'crm.documentgenerator.document.add',
       {
           'templateId': resTemplate.data().template.id,
           'entityTypeId': '2',
           'entityId': iDealID
       },
       function(resDoc) {
           if (resDoc.error()) {
               console.error(resDoc.error());
               alert('Документ не создан: ' + resDoc.error_description());
           } else {
               alert('Документ создан');
           }
       }
   );

   $resDoc = CRest::call(
       'crm.documentgenerator.document.add',
       [
           'templateId' => $resTemplate['result']['template']['id'],
           'entityTypeId' => '2', 
           'entityId' => $iDealID,
       ]
   );

Документ будет сформирован и метод crm.documentgenerator.document.add вернет его параметры.

"document":{
    "products":{
        "currencyId":"RUB",
        "totalSum":1500,
        "totalRows":1
    },
    "downloadUrl":"https:\\/\\/some-domain.bitrix24.ru\\/bitrix\\/services\\/main\\/ajax.php?action=crm.documentgenerator.document.download\\u0026SITE_ID=s1\\u0026id=29",
    "publicUrl":null,
    "title":"Демонстрационная реализация товара 1",
    "number":"1",
    "id":29,
    "createTime":"2025-07-09T16:29:27+03:00",
    "createdBy":27,
    "updateTime":"2025-07-09T16:29:27+03:00",
    "templateId":"39",
    "emailDiskFile":4917,
    "entityId":"1",
    "entityTypeId":"2",
    "downloadUrlMachine":"https:\\/\\/some-domain.bitrix24.ru\\/rest\\/crm.documentgenerator.document.download.json?sessid=c4ad892d7583ead4fd38666a0af85cb7\\u0026token=crm%7CYWN0aW9uPWNybS5kb2N1bWVudGdlbmVyYXRvci5kb2N1bWVudC5kb3dubG9hZCZTSVRFX0lEPXMxJmlkPTI5Jl89YlQ2SU9XeGVnR2s3NnZ5M0hGVlRxTDVaRlJtdFgyNTE%3D%7CImNybS5kb2N1bWVudGdlbmVyYXRvci5kb2N1bWVudC5kb3dubG9hZHxjcm18WVdOMGFXOXVQV055YlM1a2IyTjFiV1Z1ZEdkbGJtVnlZWFJ2Y2k1a2IyTjFiV1Z1ZEM1a2IzZHViRzloWkNaVFNWUkZYMGxFUFhNeEptbGtQVEk1Smw4OVlsUTJTVTlYZUdWblIyczNOblo1TTBoR1ZsUnhURFZhUmxKdGRGZ3lOVEU9fGM0YWQ4OTJkNzU4M2VhZDRmZDM4NjY2YTBhZjg1Y2I3Ig%3D%3D.H575mM4Mf%2Fj4PVH2Ngzb1kmkQhdScsAL75ZJkbYkALk%3D"
}

Пример кода

   document.addEventListener('DOMContentLoaded', function() {
       let filePath = 'template.docx'; // путь к локальному файлу шаблона
       let iDealID = 1; // идентификатор сделки
       let sDocName = 'Демонстрационная реализация товара';
   
       function fileToBase64(filePath) {
           return new Promise((resolve, reject) => {
               fetch(filePath)
                   .then(response => response.blob())
                   .then(blob => {
                       let reader = new FileReader();
                       reader.onload end = () => resolve(reader.result.split(',')[1]);
                       reader.oner ror = reject;
                       reader.readAsDataURL(blob);
                   });
           });
       }
   
       async function createDocument() {
           try {
               let fileContent = await fileToBase64(filePath);
   
               BX24.callMethod(
                   'crm.documentgenerator.numerator.add',
                   {
                       'fields': {
                           'name': 'Нумератор из REST',
                           'template': '{NUMBER}'
                       }
                   },
                   function(resNum) {
                       if (resNum.error()) {
                           console.error(resNum.error());
                           alert('Нумератор не добавлен: ' + resNum.error_description());
                           return;
                       }
   
                       if (resNum.data().numerator.id) {
                           BX24.callMethod(
                               'crm.documentgenerator.template.add',
                               {
                                   'fields': {
                                       'name': sDocName,
                                       'numeratorId': resNum.data().numerator.id,
                                       'region': 'ru',
                                       'users': ['UA'],
                                       'entityTypeId': ['2'],
                                       'file': fileContent
                                   }
                               },
                               function(resTemplate) {
                                   if (resTemplate.error()) {
                                       console.error(resTemplate.error());
                                       alert('Шаблон не добавлен: ' + resTemplate.error_description());
                                       return;
                                   }
   
                                   if (resTemplate.data().template.id) {
                                       BX24.callMethod(
                                           'crm.documentgenerator.document.add',
                                           {
                                               'templateId': resTemplate.data().template.id,
                                               'entityTypeId': '2',
                                               'entityId': iDealID
                                           },
                                           function(resDoc) {
                                               if (resDoc.error()) {
                                                   console.error(resDoc.error());
                                                   alert('Документ не создан: ' + resDoc.error_description());
                                               } else {
                                                   alert('Документ создан');
                                               }
                                           }
                                       );
                                   }
                               }
                           );
                       }
                   }
               );
           } catch (error) {
               console.error(error);
               alert('Ошибка: ' + error.message);
           }
       }
   
       createDocument();
   });

   $filePath = __DIR__ . '/template.docx'; // путь к локальному файлу шаблона
   $iDealID = 1; // идентификатор сделки
   $sDocName = 'Демонстрационная реализация товара';
   $resNum = CRest::call(
       'crm.documentgenerator.numerator.add',
       [
           'fields' => [
               'name' => 'Нумератор из REST',
               'template' => '{NUMBER}',
           ]
       ]
   );
   if (!empty($resNum['result']['numerator']['id']))
   {
       $resTemplate = CRest::call(
           'crm.documentgenerator.template.add',
           [
               'fields' => [
                   'name' => $sDocName,
                   'numeratorId' => $resNum['result']['numerator']['id'], // crm.documentgenerator.numerator.add
                   'region' => 'ru', // eu,de,ua,by,ru
                   'users' => [
                       'UA'//User All
                   ],
                   'entityTypeId' => ['2'], //2 — сделка в CRest::call('crm.enum.ownertype');
                   'file' => base64_encode(file_get_contents($filePath))
               ]
           ]
       );
       if (!empty($resTemplate['result']['template']['id']))
       {
           $resDoc = CRest::call(
               'crm.documentgenerator.document.add',
               [
                   'templateId' => $resTemplate['result']['template']['id'],
                   'entityTypeId' => '2', //2 — сделка в CRest::call('crm.enum.ownertype');
                   'entityId' => $iDealID,
               ]
           );
       }
   }
   if (!empty($resDoc['result']))
   {
       echo json_encode(['message' => 'Документ создан']);
   }
   elseif (!empty($resDoc['error_description']))
   {
       echo json_encode(['message' => 'Документ не создан: ' . $resDoc['error_description']]);
   }
   else
   {
       echo json_encode(['message' => 'Документ не создан']);
   }

💡 Экспертное мнение и рекомендации

Практические рекомендации:

При написании кастомных компонентов для «Как добавить шаблон и создать документ на его основе» всегда разделяйте бизнес-логику и представление (шаблон).
Используйте отладку SQL-запросов через конструкцию $wpdb->last_query или стандартный трекер Битрикса, чтобы контролировать нагрузку.

Похожая задача в бизнесе?

Помогу автоматизировать процессы и внедрить ИИ

Меня зовут Андрей Горошко. Я Full-stack разработчик и эксперт по 1С-Битрикс. Настраиваю CRM Битрикс24, разрабатываю защищенные API и создаю умных ИИ-агентов для автоматизации рутины.

Написать во ВКонтакте

или на почту: gorandvas@yandex.ru

Как добавить шаблон и создать документ на его основе

Как добавить шаблон и создать документ на его основе

Подготовим переменные

1\. Создадим нумератор документа

2\. Загрузим шаблон документа

3\. Сгенерируем документ

Пример кода

💡 Экспертное мнение и рекомендации

Практические рекомендации:

Помогу автоматизировать процессы и внедрить ИИ

Related Post

Интеграция Битрикс24 с интернет-магазином на 1С-БитриксИнтеграция Битрикс24 с интернет-магазином на 1С-Битрикс

Как использовать метод SDK crm.deal.update в Битрикс24Как использовать метод SDK crm.deal.update в Битрикс24

Получить список включаемых областей для страницы landing.template.getLandingRefПолучить список включаемых областей для страницы landing.template.getLandingRef