REST: генератор документов

Группа documentgenerator.* в REST API Битрикс24 генерирует документы по шаблонам: счета, договоры, акты и коммерческие предложения из DOCX-шаблонов с подстановкой данных CRM. Через REST можно управлять шаблонами, создавать документы, отдавать их в PDF и публиковать по ссылке.

Из чего состоит генератор документов

Генератор превращает DOCX-шаблон с полями-плейсхолдерами в готовый документ, подставляя значения из источника данных. Основные группы методов:

• documentgenerator.template.* — шаблоны документов;
• documentgenerator.document.* — созданные документы;
• documentgenerator.numerator.* — нумераторы (номера счетов и договоров);
• documentgenerator.region.* — региональные настройки (валюта, формат дат, разделители).

Загрузка шаблонов

Шаблон загружается методом documentgenerator.template.add. В нём указывают имя, привязку к провайдеру данных и сам DOCX-файл в base64. Плейсхолдеры в шаблоне пишутся в фигурных скобках и соответствуют полям провайдера:

documentgenerator.template.add { "fields": { "name": "Счёт на оплату", "code": "invoice", "moduleId": "crm", "providers": ["...DataProvider\\Deal"], "file": [ "invoice.docx", "UEsDBBQ..." ] } }

Список полей, доступных провайдеру, возвращает documentgenerator.template.getfields. По этому списку удобно проверять, какие плейсхолдеры допустимы в шаблоне, включая табличные блоки для позиций товаров. Один шаблон можно привязать сразу к нескольким провайдерам через массив providers — тогда он подойдёт и для сделки, и для счёта, если наборы полей совпадают. Управление шаблонами дополняют методы documentgenerator.template.list, .update и .delete, поэтому библиотеку шаблонов можно вести полностью через REST.

Создание документа

Документ создаётся методом documentgenerator.document.add с указанием шаблона и идентификатора источника. Для сделки достаточно передать её id:

documentgenerator.document.add { "templateId": 12, "fields": { "DocumentType": "deal" }, "value": 4501, "values": { "CustomField": "Дополнительное значение" } }

1. templateId — какой шаблон применить;
2. value — идентификатор сущности-источника (например, сделки);
3. values — дополнительные значения, которых нет в провайдере.

В ответе придут ссылки на документ, включая downloadUrl и pdfUrl. Готовый документ также сохраняется и доступен через documentgenerator.document.get.

Поля, провайдеры и таблицы

Провайдер — это класс, который отдаёт данные для подстановки. Штатные провайдеры CRM покрывают сделку, счёт, компанию и контакт. Поля бывают простыми (строка, число, дата) и составными:

Табличные поля позволяют выводить товарные позиции сделки построчно: в DOCX-шаблоне строку таблицы оборачивают в блок, который повторяется по числу позиций, а внутри используют плейсхолдеры вроде названия, количества, цены и суммы. Денежные и числовые поля форматируются по региональным настройкам из documentgenerator.region.* — разделители разрядов, символ валюты и формат даты. Проверять доступные поля и их коды всегда стоит через documentgenerator.template.getfields, а для готового документа — documentgenerator.document.getfields, который вернёт уже подставленные значения.

Нумераторы и публичные ссылки

Чтобы документы получали сквозные номера (Счёт № 000123), настраивают нумератор через documentgenerator.numerator.* с шаблоном номера и правилами сброса. Номер подставляется в документ автоматически при создании.

Готовый документ можно опубликовать по внешней ссылке методом documentgenerator.document.enablepublicurl — клиент откроет его без входа в портал. Отключение публикации — обратным вызовом с флагом.

PDF и хранение

Битрикс24 конвертирует документ в PDF на своей стороне; ссылка приходит в pdfUrl. Дополнительно документ можно выгрузить методом documentgenerator.document.upload или связать с Диском для дальнейшей обработки — например, отправить на подпись через сервис Sign.

• получить документ и ссылки — documentgenerator.document.get;
• список документов — documentgenerator.document.list;
• удалить — documentgenerator.document.delete.

Так генератор встраивается в цепочку: сделка → документ по шаблону → PDF → Диск → подпись или отправка клиенту. Всю эту цепочку удобно запускать из бизнес-процесса или робота CRM: при переходе сделки в нужную стадию автоматически создаётся счёт по шаблону, сохраняется на Диск и уходит клиенту письмом. Так документооборот перестаёт зависеть от того, вспомнит ли менеджер сформировать документ вручную.

Итог

Группа documentgenerator.* автоматизирует выпуск документов: шаблоны DOCX с плейсхолдерами, провайдеры данных CRM, нумераторы, PDF и публичные ссылки. Порядок работы — загрузить шаблон, сверить поля через getfields, создать документ по сущности и отдать клиенту ссылку или PDF, аккуратно управляя публичным доступом.

Мы настраиваем генерацию счетов, договоров и актов из CRM Битрикс24, готовим шаблоны с табличными позициями и нумерацией, встраиваем документы в бизнес-процессы и обмен с Диском и подписью. Если нужно автоматизировать документооборот в Битрикс24 — поможем выстроить всю цепочку.