В DocuGenerate можно превратить один оформленный шаблон Word в серию договоров, счетов, писем, сертификатов или отчётов: сервис находит поля подстановки, принимает данные из формы, таблицы или JSON, создаёт отдельные документы либо объединённый файл и выгружает результат в PDF, DOCX, DOC, ODT или TXT. Основные инструменты рабочего процесса — загрузка шаблона, проверка найденных тегов, выбор источника данных, настройка формата и объединения, подтверждение генерации и история готовых файлов.

Работа строится вокруг карточки шаблона. Слева показывается предварительный просмотр страниц, а справа находятся вкладки и раскрывающиеся панели с тегами, настройками и списком документов. Такой макет позволяет одновременно видеть исходную верстку и контролировать, какие поля сервис распознал, какие разделители используются и какие результаты уже созданы по этому шаблону.

Для разового документа данные можно ввести в автоматически построенную форму; для массовой обработки подходят XLSX, XLS, ODS, CSV и TSV; для вложенных объектов, массивов строк и сложных условий удобнее JSON. На этапе Merge options задаются выходной формат, способ упаковки результатов, разрывы страниц и добавление PDF-приложения, а на последнем шаге — логическое имя документа и фактическое имя файла.

Как устроен рабочий процесс DocuGenerate

Первое действие — подготовить документ в привычном текстовом редакторе и заменить изменяемые значения тегами. В счёте это могут быть поля клиента, номер и дата документа, позиции, количество, цена, налог и итог; в договоре — реквизиты сторон, срок, сумма и переменные пункты; в сертификате — имя участника, название курса и дата выдачи. Постоянный текст, стили, таблицы, колонтитулы, номера страниц и фоновые элементы остаются частью исходного файла, поэтому внешний вид определяется самим шаблоном, а не отдельным конструктором внутри сервиса.

После загрузки файл превращается в карточку шаблона. Сервис строит предварительный просмотр, извлекает теги и группирует их в боковой панели. Пользователь может щёлкнуть по найденному тегу и увидеть соответствующее место на странице. Такой контроль особенно полезен перед массовой генерацией: легко заметить поле, которое набрано с лишним пробелом, закрыто другим символом или случайно разбито форматированием Word.

Затем создаётся новый документ. Мастер последовательно проводит через источник данных, набор записей, параметры объединения и подтверждение. Каждый объект JSON, каждая выбранная строка таблицы или один заполненный формуляр считаются отдельным элементом данных. Из одного элемента получается один персонализированный документ; несколько элементов можно собрать в общий файл или выдать как набор отдельных файлов в ZIP.

В конце операция попадает в историю конкретного шаблона. В списке отображаются имя, время создания, формат и число использованных элементов данных. Для PDF доступен просмотр прямо в интерфейсе; остальные форматы требуется скачать. Рядом с каждой записью находятся действия просмотра, загрузки и удаления, поэтому история служит не только журналом, но и рабочей точкой возврата к готовым материалам.

Создание и загрузка шаблона

В окне Create a new template выбирают файл и при необходимости задают понятное имя. Если поле имени оставить пустым, сервис использует имя загруженного файла. Это удобно для пробного запуска, но в рабочей библиотеке лучше сразу применять устойчивые названия: Счёт B2B, Договор оказания услуг, Сертификат курса. По такому имени затем проще искать шаблон и отличать его от документов, созданных на его основе.

Поддерживаются DOCX и DOC, текстовые документы ODT и TXT, а также SQL-шаблоны. Для сложной верстки практичнее DOCX: он сохраняет таблицы, отступы, стили, колонтитулы, нумерацию и графические элементы. ODT подходит командам, которые оформляют документы в LibreOffice. TXT и SQL уместны, когда нужен не печатный макет, а текстовый результат с подстановкой значений.

Содержимое шаблона редактируется вне DocuGenerate. Если требуется изменить формулировку, переставить блок, добавить колонку или поправить стиль, исходный файл открывают в Word либо совместимом редакторе, сохраняют и загружают повторно через область обновления. Это сохраняет привычные возможности верстки, но требует следить, чтобы автор шаблона не удалил теги и не изменил их написание без синхронного обновления данных.

При повторной загрузке карточка остаётся той же, а содержимое обновляется. Перед заменой стоит скачать текущий шаблон или использовать историю версий, если она доступна в тарифе. Такой порядок снижает риск потерять рабочий вариант после неудачной правки: сначала сохраняют проверенную копию, затем загружают новый файл, просматривают теги и выполняют тестовую генерацию на одной записи.

Теги подстановки и их автоматическое распознавание

Тег подстановки — это имя поля данных, заключённое в выбранные разделители. Например, тег [Company Name] заменяется значением поля Company Name, а [Invoice No] — номером счёта. Названия чувствительны к точному совпадению: разное написание, лишний пробел или другое имя колонки приводят к тому, что значение не находится. Если соответствующего поля нет, в готовом документе на месте тега появляется пустая строка.

После загрузки DocuGenerate сканирует текст и выводит найденные теги в панели Templates. Для шаблона счёта там могут появиться Company Name, Street Address, Invoice Date, Item Title, Amount и Sub Total. Щелчок по тегу подсвечивает его на странице, поэтому можно быстро проверить, что каждое поле относится к нужному месту и не осталось скрытых тегов в колонтитулах или таблицах.

Проверка должна охватывать не только количество полей, но и структуру. Поле суммы в верхней части счёта и итог в таблице могут иметь похожие названия, однако должны получать разные значения. Для повторяющихся строк важно, чтобы теги находились в правильной строке таблицы между открывающим и закрывающим тегами цикла. Для условий нужно убедиться, что начало и конец блока не пересекаются с соседними секциями.

Панель также показывает проблемы распознавания. Незакрытый тег, несовпадающие разделители или разрыв текста могут перевести шаблон в состояние с ошибками. Массовую генерацию лучше не запускать, пока список не станет ожидаемым: одна пропущенная закрывающая скобка способна убрать значение или вывести служебную конструкцию в итоговый документ.

Разделители тегов

DocuGenerate автоматически проверяет распространённые пары разделителей: двойные фигурные скобки, одинарные фигурные скобки, двойные квадратные скобки, одинарные квадратные скобки, французские кавычки, угловые скобки и двойные круглые скобки. Поэтому шаблон можно адаптировать под уже существующие документы, где квадратные скобки заняты обычным текстом или фигурные скобки используются для других обозначений.

Левый и правый разделители задаются отдельно в настройках шаблона. Если в документе используются {{Customer Name}}, слева выбирают {{, справа }}. Для [Customer Name] устанавливают [ и ]. Разделители должны быть единообразными во всём шаблоне: смешивание нескольких пар ухудшает распознавание и усложняет поиск ошибок.

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

После изменения разделителей сервис повторно анализирует файл. Список тегов должен обновиться, а предупреждение исчезнуть. Затем стоит проверить несколько ключевых полей в разных частях документа и выполнить тест на одной записи. Если часть тегов всё ещё не распознана, их нужно перепечатать без копирования форматированных фрагментов: Word иногда делит визуально цельную конструкцию на несколько текстовых участков.

Ручной ввод данных через форму

Источник Fill out a form предназначен для единичных документов. После выбора этого режима DocuGenerate строит форму по найденным тегам. Каждое поле соответствует одному тегу, а порядок обычно повторяет структуру, обнаруженную в шаблоне. Пользователь вводит значения прямо в браузере и переходит к параметрам объединения кнопкой Continue with one item.

Поля формы не обязательны. Можно заполнить только те значения, которые нужны для конкретного экземпляра, но незаполненные теги превратятся в пустые места. Поэтому для договоров и счетов полезно заранее определить минимальный набор: наименование стороны, дата, номер, сумма и реквизиты. Отсутствие обязательности на уровне интерфейса не заменяет бизнес-проверку данных.

Форма умеет работать с повторяющимися списками и строками таблиц. Рядом с массивом появляется кнопка добавления элемента; для каждой новой позиции выводится набор вложенных полей. В счёте можно по очереди добавить товар, количество, цену и сумму, а лишнюю строку удалить значком корзины. Этот режим удобен, когда оператор готовит один документ и не хочет создавать отдельный Excel-файл.

Для сложных структур ручная форма становится длинной. Если шаблон содержит десятки полей, вложенные таблицы и несколько условных разделов, ввод занимает больше времени и повышает риск пропуска. В таком случае данные лучше получать из CRM или базы через интеграцию либо подготовить JSON, где обязательность и типы значений проверяются до отправки.

Генерация из Excel, CSV и других таблиц

Режим Excel or CSV file принимает XLSX, XLS, ODS, CSV и TSV. Файл можно перетащить в область загрузки или выбрать через системный диалог. После чтения DocuGenerate показывает данные таблицей: столбцы сопоставляются с тегами, строки становятся отдельными элементами для генерации. Заголовки колонок должны точно совпадать с именами тегов без разделителей.

Если книга содержит несколько листов, сервис предлагает выбрать нужный. Это важно для файлов, где справочники, расчёты и итоговая выборка находятся на разных вкладках. Для генерации лучше использовать лист с плоской таблицей: первая строка содержит заголовки, каждая следующая строка — одну завершённую запись. Объединённые ячейки и многоуровневые заголовки затрудняют корректное чтение.

После загрузки видны все строки и столбцы. Таблицу можно развернуть на весь экран, чтобы проверить широкие наборы данных. По умолчанию выбраны все строки; щелчком пользователь оставляет только нужные. Кнопка перехода показывает число выбранных элементов, поэтому перед запуском легко сверить объём партии с ожидаемым количеством документов.

Табличный источник хорошо подходит для писем, сертификатов, простых счетов и однотипных договоров, где одна строка содержит все значения. Для вложенных массивов, например нескольких товаров внутри каждого счёта, плоская таблица менее удобна. Можно заранее агрегировать позиции в отдельные текстовые поля, но для настоящих повторяющихся строк предпочтительнее JSON или ручная форма с динамическими элементами.

Перед массовой генерацией полезно проверить формат дат и чисел. Табличный редактор может хранить дату как внутреннее число, автоматически удалять ведущие нули в индексах и артикулах или преобразовывать длинные идентификаторы в экспоненциальную запись. Критичные поля следует форматировать как текст и просмотреть в таблице DocuGenerate после загрузки.

Работа с JSON

JSON подходит для сложных данных, вложенных объектов и массивов. В интерфейсе требуется массив объектов: внешние квадратные скобки содержат одну или несколько записей, а каждый объект в фигурных скобках соответствует отдельному документу. Даже для одного документа данные следует передать массивом из одного объекта.

После выбора источника поле ввода заполняется примером, построенным по тегам шаблона. Это полезная заготовка: она показывает ожидаемые ключи и снижает риск опечатки. Пользователь заменяет демонстрационные значения своими, а кнопка продолжения отображает число объектов, которые удалось разобрать.

Ключи должны совпадать с тегами. Для обычного режима можно передавать ключ с точкой как буквальное имя, но при включённом расширенном синтаксисе точка обращается к вложенному свойству. Например, тег [client.name] читает свойство name внутри объекта client. Такой формат удобен, когда данные приходят из API и уже имеют иерархическую структуру.

Ошибки JSON чаще всего связаны с пропущенной запятой, одинарными кавычками вместо двойных, незакрытой скобкой или лишней запятой после последнего поля. Перед вставкой большой структуры полезно проверить её валидатором в исходной системе. Если кнопка продолжения не показывает ожидаемое число элементов, сначала нужно исправить синтаксис, а затем сверить типы: массив должен находиться на верхнем уровне.

Для пакетной генерации каждый объект обрабатывается как самостоятельная запись. Массив из ста объектов создаёт сто персонализированных документов, хотя результат может быть объединён в один файл. Это различие важно для учёта использования: количество документов определяется числом элементов данных, а не числом скачанных файлов.

Списки и повторяющиеся блоки

Массив примитивных значений выводится циклом. Открывающий тег [#items] начинает повторение, [.] вставляет текущий элемент, а [/items] или короткий [/] завершает блок. Если массив содержит названия услуг, каждая итерация создаёт очередной пункт списка с тем же оформлением, что задано в Word.

Для массива объектов внутри цикла используются свойства текущего элемента. Конструкция [#items], затем [name] и [quantity], после чего закрывающий тег, создаёт строки вида Название: количество. Вложенные объекты позволяют хранить у позиции цену, налог, скидку, описание и другие атрибуты, не создавая отдельные верхнеуровневые поля для каждой строки.

Форматирование повторяется вместе с содержимым. Если теги находятся в маркированном абзаце, каждый элемент получает маркер; если в нумерованном — номер. Чтобы избежать пустого пункта после списка, открывающий и закрывающий теги размещают в пределах повторяемого абзаца, а не на отдельных строках с собственным маркером.

Для пустого массива блок не выводится. Это можно использовать для необязательных приложений: раздел Оборудование появится только при наличии элементов. Если нужно вывести альтернативную фразу, рядом добавляют отрицательное условие, которое срабатывает для пустого массива.

Динамические таблицы

Повторяющуюся строку таблицы строят тем же циклом. Открывающий тег помещается в первую ячейку строки перед первым полем, закрывающий — в последнюю ячейку после последнего поля. При обработке строка копируется для каждого объекта массива, а значения name, quantity и price подставляются в свои колонки.

Шапка таблицы, границы, заливка и выравнивание задаются в исходном DOCX. DocuGenerate размножает строку, сохраняя её оформление. Поэтому итог зависит от качества шаблона: узкие колонки будут переносить длинные названия, фиксированная высота может обрезать текст, а чрезмерно сложные объединения ячеек способны дать непредсказуемую верстку.

Расчётные значения можно передавать готовыми из источника данных либо вычислять выражениями при включённом расширенном синтаксисе. Для бухгалтерских документов надёжнее рассчитывать налоги и итог в учётной системе, а в шаблоне только форматировать результат. Так единые правила округления остаются в источнике и не расходятся между документами.

При тестировании таблицы нужно проверить короткие и длинные наборы: одну строку, несколько строк и количество, которое переносит таблицу на следующую страницу. Также следует протестировать длинное описание, нулевую цену и пустое необязательное поле. Такой набор выявляет проблемы верстки до массового запуска.

Условия и необязательные разделы

Условный блок начинается тегом [#condition] и заканчивается [/condition] или [/]. Он выводится, когда значение истинно. Отрицательный вариант [^condition] показывает содержимое, когда значение ложно, равно null, пустой строке, нулю или пустому массиву. Это позволяет скрывать целые абзацы, строки таблиц и приложения.

В договоре условием можно управлять разделом о предоплате, в счёте — строкой скидки, в письме — персональным обращением, в отчёте — блоком предупреждений. Теги следует размещать так, чтобы при скрытии не оставались пустые заголовки или лишние разрывы. Если исчезает весь раздел, открывающий тег ставят перед заголовком, а закрывающий — после последнего абзаца раздела.

При включённом расширенном синтаксисе доступны сравнения и логические выражения. Условие может проверять возраст, страну, сумму заказа или число элементов, использовать операторы больше, меньше, равно, не равно, AND и OR. Строковые значения заключают в двойные кавычки, для сравнения применяют двойной знак равенства.

Сложные условия стоит держать читаемыми. Вместо длинной формулы в шаблоне можно передать из исходной системы готовый логический флаг вроде show_discount или include_appendix. Тогда бизнес-правило тестируется в одном месте, а шаблон отвечает только за отображение. Выражения полезны для простых порогов и выбора короткого текста, но не должны превращать DOCX в скрытую программу расчёта.

Расширенный синтаксис

Enhanced syntax отключён при создании шаблона и включается отдельным флажком в Settings. После активации можно обращаться к вложенным свойствам через точку, использовать арифметические и логические выражения, тернарный оператор и фильтры. Перед включением стоит проверить существующие имена полей с точками: они начнут трактоваться как путь к вложенному объекту.

Поддерживаются сложение, вычитание, умножение, деление, остаток от деления, сравнения, логические AND и OR, присваивание и приоритет в круглых скобках. Выражение может вывести результат непосредственно в документ или управлять условием. Например, проверка длины массива позволяет менять заголовок Позиция на Позиции либо показывать предупреждение при нескольких элементах.

Тернарное выражение удобно для короткого выбора: одно значение выводится при истинном условии, другое — при ложном. Для больших текстовых блоков лучше использовать секции, потому что они легче читаются в Word. Если формула становится длинной, её следует вынести в данные и передавать уже рассчитанный результат.

После включения расширенного синтаксиса нужен отдельный тест на граничных значениях: ноль, пустая строка, null, пустой массив, отрицательное число и отсутствующее свойство. Разные типы могут вести себя по-разному в арифметике и условиях. Тестовый JSON должен включать не только нормальный пример, но и записи, где необязательные поля отсутствуют.

Форматирование дат, чисел и текста

Фильтры добавляются после поля через вертикальную черту. Для даты используется конструкция вида [source_date | date:'dd-MM-yyyy']. Исходное значение должно быть представлено в формате ISO 8601. Маска определяет порядок дня, месяца и года, наличие времени, полное или сокращённое название месяца и день недели.

Для международных документов полезно создавать отдельные шаблоны или передавать нужную локаль через данные. Один и тот же ISO-источник можно вывести как 15-06-2025, 15/06/2025, June 15, 2025 или с часами и минутами. Важно различать символы месяца и минут и проверять результат на реальной дате, где день и месяц не совпадают.

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

Для текста доступны преобразование к верхнему и нижнему регистру и удаление лишних пробелов по краям. Uppercase полезен для кодов и заголовков, lowercase — для технических идентификаторов, trim — для данных из форм и CSV. Эти фильтры исправляют представление, но не заменяют очистку источника: внутренние двойные пробелы, ошибочные символы и неверные значения нужно устранять до генерации.

Изображения из URL и Base64

Динамическое изображение вставляется тегом с процентом, например [%logo]. В данных ключ называется logo без символа процента, а значение содержит адрес изображения. При генерации сервис загружает файл и ставит его на место тега. Так можно подставлять логотип клиента, фотографию сотрудника, подпись, схему или изображение товара.

Если изображение недоступно по указанному адресу, оно игнорируется. В готовом документе останется пустое место, поэтому внешние файлы должны открываться без авторизации и временных cookies. Для защищённых данных лучше передавать изображение в Base64 или использовать URL с контролируемым временем жизни, достаточным для обработки.

Base64 передаётся как data URI с указанием типа, например PNG или JPEG. Такой подход увеличивает размер JSON, но не зависит от внешней загрузки. Он удобен для подписей и небольших логотипов, которые уже находятся в базе. Очень большие фотографии раздувают запрос и выходной PDF, поэтому их следует заранее уменьшать до требуемого печатного размера.

Размер и пропорции изображения задаются фильтрами расширенного синтаксиса. При подготовке шаблона нужно оставить достаточно места и проверить горизонтальные, вертикальные и квадратные исходники. Если важна единая композиция, изображения лучше предварительно обрезать в исходной системе, а в шаблон передавать уже нормализованные варианты.

QR-коды и штрихкоды

QR-код создаётся из текста или адреса фильтром qrcode в теге изображения. Можно указать ширину и высоту, включая автоматическое вычисление одной стороны. В сертификате код ведёт на страницу проверки, в счёте — на оплату, в пропуске — кодирует идентификатор. Перед массовой печатью код следует проверить камерой телефона и убедиться, что контраст и размер достаточны.

Штрихкод формируется аналогичным фильтром barcode. Исходная строка должна соответствовать назначению документа и правилам системы, которая будет её считывать. DocuGenerate создаёт графическое представление, но не проверяет бизнес-валидность складского или транспортного идентификатора. Контроль длины и допустимых символов должен происходить до отправки данных.

Для обоих фильтров требуется включённый расширенный синтаксис. Если в готовом документе вместо кода остаётся текст тега, сначала проверяют этот параметр, затем написание фильтра и наличие значения в JSON. При пустом поле код не может быть построен, поэтому для необязательных значений полезно обернуть тег условием.

Выбор выходного формата

В Merge options доступны PDF, DOCX, DOC, ODT и TXT. PDF подходит для отправки и печати, когда верстка должна оставаться неизменной. DOCX выбирают, если получатель будет редактировать результат или согласовывать его в Word. DOC сохраняет совместимость со старыми рабочими процессами, ODT — с LibreOffice, TXT — с системами, которым нужен только текст без оформления.

DOCX создаётся быстрее PDF, потому что для PDF требуется дополнительное преобразование. Среднее время, указанное в справке, составляет около одной-двух секунд для DOCX и трёх-шести секунд для PDF. Реальное время зависит от объёма, изображений, числа страниц и очереди, поэтому эти значения стоит воспринимать как ориентир для обычного документа.

Предварительный просмотр в кабинете работает только для PDF. DOCX, DOC, ODT, TXT и ZIP необходимо скачать и открыть подходящей программой. Если рабочий процесс включает визуальную проверку оператором, практично генерировать PDF. Если документ затем редактирует юрист или менеджер, лучше выводить DOCX и проверять его в Word.

При выборе TXT теряются стили, таблицы и изображения, поскольку формат содержит только текст. Этот вариант полезен для писем, SQL-скриптов и обмена с системами, которым не нужна верстка. Для печатных форм следует оставаться на PDF или DOCX.

Объединённый файл, отдельные документы и разрывы страниц

Параметр Combine all documents in a single file определяет упаковку партии. При значении Yes результаты объединяются в один файл выбранного формата. Такой режим подходит для общей ведомости, пакета писем на печать или сводного отчёта. При значении No сервис создаёт ZIP, где каждому элементу данных соответствует отдельный файл.

Если документы объединяются, появляется переключатель Insert a page break after each document. Значение Yes начинает каждый экземпляр с новой страницы; No ставит их последовательно без принудительного разрыва. Для договоров, счетов и писем обычно нужен разрыв, иначе следующий документ может начаться сразу после предыдущего на той же странице.

В ZIP файлы по умолчанию получают имя документа и порядковый номер, начиная с единицы. Для партии Invoices внутри окажутся Invoices 1.pdf, Invoices 2.pdf и далее. В Advanced options можно использовать теги в имени каждого файла, например номер счёта и компанию, если документы создаются раздельно.

Динамические имена поддерживаются не во всех комбинациях. При одиночной генерации теги разрешены и в логическом имени, и в имени файла. В ZIP логическое имя служит именем архива и не подставляется из каждой записи, зато имя отдельных файлов может содержать теги. В объединённом пакетном файле динамические имена не применяются, потому что весь результат имеет одно имя.

Добавление PDF-приложения

В Advanced options можно прикрепить существующий PDF в конец создаваемого документа. Функция доступна только при выходном формате PDF. Она подходит для стандартных условий, приложения с реквизитами, инструкции, политики конфиденциальности или неизменяемой технической спецификации.

Если создаётся партия отдельных документов, выбранное приложение добавляется в конец каждого файла. Поэтому перед запуском нужно учитывать увеличение размера и числа страниц. Для объединённого результата также следует проверить ожидаемое расположение: приложение должно относиться к каждому экземпляру либо к общему пакету в зависимости от выбранной схемы.

Загруженный PDF можно очистить и заменить до перехода к подтверждению. Практично хранить приложения с понятными версиями и датами, потому что интерфейс прикрепляет конкретный файл, а не автоматически обновляемую ссылку. После изменения условий нужно выбрать новый PDF и выполнить тестовую генерацию.

Имена документов и файлов

На шаге Confirmation поле Document name задаёт логическое имя записи в истории. Если его не заполнить, используется имя шаблона. В Advanced options поле File name определяет имя скачиваемого файла; расширение вводить не нужно, оно добавляется автоматически по выбранному формату.

Для одиночного документа в обоих полях можно использовать теги. Это позволяет получить запись Счёт 1038 и файл Invoice 1038 for Acme.pdf. Разделители должны совпадать с настройками шаблона. Если тег не существует в данных, соответствующая часть имени окажется пустой, поэтому шаблоны имён лучше тестировать на записи с заполненными и незаполненными полями.

В пакетах имена должны оставаться уникальными. Если несколько объектов дают одинаковое имя, файлы трудно различать после распаковки. Надёжная схема включает номер, дату или уникальный идентификатор. Символы, запрещённые в именах файлов разных операционных систем, следует удалять в источнике данных.

История созданных документов

Список Documents находится внутри карточки шаблона и сортируется от новых записей к старым. Каждая строка показывает имя, время, формат и количество элементов данных. Значок глаза открывает PDF, стрелка загружает файл, корзина удаляет запись после подтверждения.

Файлы хранятся до явного удаления. При удалении документа или шаблона связанные файлы удаляются без восстановления, поэтому готовые материалы, которые нужны для архива, следует выгружать в корпоративное хранилище. API может вернуть результат в бинарном виде без сохранения, если политика требует не оставлять сгенерированные документы в кабинете.

История привязана к шаблону. Если оператор не видит нужный файл, сначала проверяют, открыт ли правильный шаблон, затем сортировку и время запуска. Для длительной партии может отображаться состояние обработки. После завершения запись становится доступна для просмотра или скачивания.

Удаление требует подтверждения, что защищает от случайного нажатия. Однако массовую очистку лучше выполнять после резервного копирования. Для документов с персональными данными полезно установить внутренний срок хранения и регулярно удалять устаревшие результаты из кабинета.

Скорость, очереди и параллельные запросы

Обычный DOCX обрабатывается быстрее PDF, поскольку не проходит этап конвертации. Большие таблицы, изображения Base64, многостраничные приложения и сложные шаблоны увеличивают время. Для оценки производительности следует измерить реальный документ с типичным объёмом данных, а не пустой тестовый файл.

У аккаунта есть лимит параллельно обрабатываемых документов. Когда он исчерпан, новый запрос отклоняется ошибкой, пока один из текущих не завершится. Пакет из множества элементов считается одним параллельным документом, потому что элементы внутри партии обрабатываются последовательно. Это делает пакетный режим удобным для больших выгрузок, но время всей партии растёт с числом записей.

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

Для срочных документов полезно отделить интерактивные запросы от ночных массовых партий. Большую рассылку запускают в менее загруженное время, а одиночные договоры и счета оставляют в отдельном потоке. Если скорость критична и редактируемый результат приемлем, DOCX может быть предпочтительнее PDF.

API и автоматическая генерация

REST API управляет шаблонами и документами. Типовой сценарий состоит из загрузки шаблона, получения его идентификатора, отправки данных и параметров генерации, ожидания результата и сохранения файла. API-ключ создаётся в настройках аккаунта и передаётся как секрет; его нельзя помещать в клиентский JavaScript или публиковать в репозитории.

Для тестирования доступны справочник API и Postman. Сначала удобно выполнить запрос на одном простом шаблоне и одном объекте, затем добавить вложенные массивы, условия и пакетную обработку. Ошибки следует логировать вместе с кодом ответа и идентификатором шаблона, но без персональных данных и самого API-ключа.

Документ можно получить ссылкой либо в бинарном виде. Бинарный ответ позволяет сразу записать файл в CRM, облачное хранилище или отправить по электронной почте, не оставляя копию в истории. Для больших файлов приложение должно поддерживать потоковую передачу и достаточный тайм-аут.

Региональные конечные точки помогают обрабатывать и хранить файлы в выбранной географической зоне. Регион шаблона и endpoint должны соответствовать настройкам аккаунта. При переносе процесса между регионами следует проверить идентификаторы, доступность шаблона и адрес API, а не только заменить домен в запросе.

Для пакетной генерации массив данных передают одной операцией. Такой запрос проще контролировать, чем сотни одновременных вызовов, и он расходует один слот параллельной обработки. Недостаток — результат готов только после последовательной обработки всей партии; для мгновенной выдачи отдельных документов лучше использовать очередь с ограниченным числом параллельных задач.

Интеграции без собственного кода

Готовые интеграции охватывают Zapier, Make, n8n и Pipedream. В сценарии выбирают действие генерации, указывают шаблон, передают данные из предыдущего шага и получают готовый файл или ссылку. Триггером может быть новая запись формы, сделка в CRM, строка таблицы, оплата или событие приложения.

Make предоставляет действие Generate a Document и триггеры, связанные с новыми документами и шаблонами. n8n и Pipedream подходят для более технических цепочек с преобразованием JSON, ветвлением и обработкой ошибок. Zapier удобен для линейных процессов, где данные проходят из одного приложения в другое без сложной логики.

Для Power Automate и Power Apps доступен коннектор с операциями генерации, получения, обновления и удаления документов, а также просмотра и удаления шаблонов. Подключение использует API-ключ. При совместном использовании приложения каждый пользователь может быть обязан создать собственное соединение, поэтому доступы нужно планировать заранее.

Интеграции с Bubble, Coda, Xano и Backendless позволяют добавить генерацию в приложение без отдельного сервера. Однако структура данных всё равно должна соответствовать тегам. Перед включением сценария в рабочий процесс полезно сохранить тестовый payload и эталонный PDF, чтобы после изменения шаблона быстро проверить совместимость.

Ошибки автоматизации чаще всего возникают из-за переименованного тега, удалённого шаблона, неверного API-ключа, превышения параллельного лимита или недоступного изображения. Сценарий должен записывать причину, исходный идентификатор записи и состояние повторной попытки. Уведомление оператору должно содержать достаточно информации для исправления, но не раскрывать секреты.

Организация шаблонов, команды и версии

Шаблоны можно группировать по папкам и вложенным папкам. Практичная структура отражает процессы: Продажи / Предложения, Финансы / Счета, HR / Письма и сертификаты. Папка не заменяет понятное имя, но сокращает список и помогает разграничить наборы по отделам.

При назначении шаблона папке важно договориться, кто отвечает за его содержимое. Изменения тегов влияют на API и интеграции, поэтому редактор шаблона должен согласовывать новые поля с разработчиком или владельцем автоматизации. Полезно хранить краткое описание ожидаемых ключей рядом с исходным DOCX в корпоративном репозитории.

Командные возможности позволяют добавлять участников и делиться шаблонами. Доступность числа участников зависит от плана. Для безопасной работы каждому сотруднику следует выдавать собственную учётную запись, а API-ключи хранить отдельно от пользовательских паролей. После ухода сотрудника его доступ нужно отозвать.

История версий шаблона помогает восстановить прежний файл после неудачного обновления, но доступна не во всех планах. Если функция недоступна, версии следует хранить вне сервиса с датой и номером изменения. Перед заменой рабочей версии нужно скачать текущий шаблон и сохранить тестовые данные.

Пользовательские шрифты доступны в старших настройках. Перед их применением следует проверить лицензию на серверное встраивание, начертания и поддержку кириллицы. Если шрифт отсутствует или не содержит нужные символы, замена может изменить переносы строк и число страниц. Для юридических форм лучше использовать распространённые шрифты либо тестировать весь набор символов.

Хранение данных и приватность рабочего процесса

Данные, переданные для слияния, используются во время генерации и не сохраняются как отдельный набор. Готовые файлы при обычной работе остаются в истории до удаления. Это различие важно: исходный JSON может не храниться, но персональные сведения продолжают существовать внутри созданного PDF или DOCX.

Для чувствительных документов нужно выбрать подходящий регион обработки, ограничить доступ к аккаунту и определить срок хранения. После передачи файла в CRM или архив копию в DocuGenerate можно удалить. Если используется бинарный ответ API без сохранения, приложение само отвечает за защищённую передачу и хранение.

Ссылки на внешние изображения могут раскрывать факт обращения к стороннему серверу и зависят от его доступности. Для конфиденциальных логотипов, подписей и фотографий безопаснее использовать Base64 либо контролируемое хранилище. Временная ссылка должна действовать дольше максимального времени ожидания в очереди.

API-ключ даёт доступ к операциям аккаунта и требует тех же мер, что пароль: хранение в менеджере секретов, ограничение доступа, ротация при подозрении на утечку и отсутствие в журналах. При создании нового ключа интеграции следует обновить согласованно, чтобы не остановить генерацию.

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

Шаблон счёта обычно содержит статические реквизиты поставщика, теги покупателя, номер и дату, таблицу позиций и итоговые суммы. Данные одной сделки передаются объектом, а позиции — массивом items. Строка таблицы оборачивается циклом, логотип вставляется как обычное или динамическое изображение, а условия скрывают скидку и налог, если они не применяются.

Для одной сделки менеджер может заполнить форму и добавить позиции кнопкой плюс. Для массовой выгрузки простых счетов подходит таблица, если каждая строка уже содержит агрегированные позиции. Для полноценных многопозиционных счетов лучше JSON из учётной системы, где каждая запись содержит вложенный массив товаров.

Имена файлов удобно строить из номера и клиента. При раздельной генерации ZIP получит общее имя партии, а каждый PDF — индивидуальное. В конец можно добавить стандартные условия оплаты. Перед отправкой проверяют формат валюты, округление, перенос длинных названий и наличие разрыва страницы между счетами.

Если сумма или налог рассчитываются в шаблоне, нужно протестировать дробные значения и правила округления. Более надёжно передавать готовые суммы из бухгалтерской системы, а фильтром только оформлять число. Так PDF будет совпадать с записью в учёте.

Практический сценарий: договоры и приложения

В договоре теги заменяют реквизиты сторон, даты, суммы, сроки и адреса. Условия включают отдельные пункты для предоплаты, физического лица, НДС или конкретного способа доставки. Повторяющийся массив может сформировать перечень услуг, этапов или оборудования.

Постоянные юридические формулировки остаются в DOCX, поэтому юрист редактирует их привычными средствами Word. После изменения текста шаблон загружают заново, проверяют теги и сравнивают тестовый PDF с утверждённой версией. Если история версий недоступна, предыдущий DOCX сохраняют отдельно.

Стандартное приложение можно прикрепить готовым PDF. Если приложение должно отличаться для каждого договора, его данные лучше включить в сам шаблон или создавать отдельным процессом. Одна выбранная PDF-вставка добавляется одинаково ко всем документам партии.

Для подписания документ обычно передают дальше в сервис электронной подписи через интеграцию. Перед отправкой нужно убедиться, что файл окончательный, имя уникально и обязательные поля заполнены. DocuGenerate формирует документ, но статус подписания контролируется уже в следующей системе.

Практический сценарий: сертификаты, письма и отчёты

Сертификат удобно генерировать из таблицы участников. Каждая строка содержит имя, курс, дату и идентификатор. QR-код может вести на страницу проверки. Выход лучше создавать отдельными PDF с динамическими именами, чтобы затем отправить каждому участнику его файл.

Для писем данные из CRM или CSV подставляют в обращение, адрес и персональный текст. Условие выбирает приветствие и скрывает необязательный абзац. Пакет можно объединить с разрывом страницы для печати или оставить раздельным для электронной рассылки.

Отчёт использует вложенные объекты, таблицы и изображения. Числовые показатели передаются готовыми, даты форматируются фильтрами, а изображения графиков — URL или Base64. Большие графики следует создавать в нужном разрешении заранее, иначе PDF станет тяжёлым и будет обрабатываться дольше.

Сертификаты и отчёты требуют проверки шрифтов. Имя с кириллицей, диакритикой или длинной фамилией может выйти за границы. Тестовый набор должен включать короткое и самое длинное значение, разные алфавиты и символы, которые реально встречаются в данных.

Типичные ошибки и способы их устранения

Тег остался в готовом документе

Сначала проверяют разделители и список найденных тегов. Затем сравнивают имя ключа с тегом, включая регистр, пробелы и точки. Если тег находится в сложном фрагменте Word, его перепечатывают целиком одним стилем. Для фильтров, QR-кодов и выражений проверяют, включён ли расширенный синтаксис.

Вместо значения появилось пустое место

Поле отсутствует в данных, имеет другое имя или пустое значение. В JSON нужно проверить нужный объект, в таблице — заголовок колонки и выбранную строку, в форме — заполнение поля. Для вложенных свойств проверяют всю цепочку, например client.address.city.

JSON не принимается

Верхний уровень должен быть массивом объектов. Используются двойные кавычки, между полями и объектами ставятся запятые, все скобки закрываются. Даже одна запись передаётся как массив из одного объекта. После исправления кнопка должна показать ожидаемое число элементов.

Таблица из Excel прочиталась неправильно

Проверяют выбранный лист, первую строку заголовков, объединённые ячейки и типы данных. Ведущие нули и длинные номера сохраняют как текст. Если файл слишком сложный, создают отдельный лист экспорта с плоской таблицей и только нужными колонками.

Изображение не появилось

Адрес должен быть доступен без входа и возвращать настоящий графический файл. Для временной ссылки проверяют срок действия. В Base64 должна присутствовать корректная приставка data:image и неповреждённые данные. Очень большой файл уменьшают до требуемого размера.

PDF создаётся дольше DOCX

Это ожидаемо из-за дополнительного преобразования. Сокращают размер изображений, убирают лишние страницы и проверяют, не добавляется ли большое PDF-приложение. Для процесса, где итог затем редактируют, можно временно использовать DOCX.

Запрос отклонён при параллельной генерации

Достигнут лимит одновременных документов. Нужно дождаться завершения текущей задачи и повторить запрос с задержкой. В автоматизации используют очередь и ограничение параллельности. Большой набор данных можно отправить одной пакетной операцией.

В ZIP одинаковые или неудобные имена

В Advanced options задают File name с уникальными тегами — номером, датой или идентификатором. Расширение не добавляют вручную. Значения очищают от символов, запрещённых в именах файлов.

После обновления шаблона сломалась интеграция

Сравнивают старый и новый набор тегов. Переименованные поля нужно одновременно изменить в CRM, сценарии или коде. Затем выполняют тест на сохранённом payload и только после проверки переводят обновлённый шаблон в рабочий процесс.

Ограничения, которые важно учитывать

В сервисе нет полноценного редактора содержимого DOCX. Он показывает предварительный просмотр и настройки, но формулировки и верстку меняют в Word или совместимом редакторе, после чего файл загружают снова. Для команды это означает необходимость хранить исходники и контролировать изменения вне кабинета.

Бесплатный режим ограничен двадцатью документами и двумя шаблонами в месяц, а также одним параллельным документом. Он подходит для знакомства и небольших задач, но не для регулярной массовой рассылки. Каждый элемент данных считается отдельным документом, даже если партия объединена в один PDF.

JSON в интерфейсе должен быть массивом объектов. Пользователь, привыкший отправлять одиночный объект, обязан обернуть его в квадратные скобки. Простые таблицы не передают вложенные массивы так естественно, как JSON, поэтому сложные счета и отчёты требуют предварительной подготовки структуры.

Прямой просмотр доступен только для PDF. DOCX, DOC, ODT, TXT и ZIP нужно скачать. Это увеличивает число действий при проверке редактируемых файлов и требует подходящей программы на устройстве.

Внешние изображения зависят от доступности URL. Если файл не загрузился, сервис пропускает его без вставки. Для критичных изображений следует использовать Base64 или собственное надёжное хранилище и проверять результат.

Сравнение DocuGenerate с аналогами

Программа	Лучше подходит для	Главное ограничение
DocuGenerate	Шаблоны Word, данные из формы, таблиц и JSON, быстрый запуск через кабинет или API	Содержимое шаблона редактируется вне сервиса
Docmosis	Сложные Word- и LibreOffice-шаблоны, API и варианты размещения в облаке или на своих серверах	Для рабочего внедрения обычно нужна разработка интеграции
Plumsail Documents	Процессы Microsoft 365, Power Automate, SharePoint, доставка файлов и электронная подпись	Широкий набор процессов сложнее простого слияния шаблона
PDFMonkey	PDF по HTML, CSS и Liquid, визуальный конструктор и разработческие сценарии	Word-шаблоны не являются основой рабочего процесса
Documint	Визуальное проектирование документов без HTML и интеграции с Airtable, HubSpot и Coda	Существующие DOCX приходится переносить в собственный редактор

DocuGenerate разумно выбирать, когда у команды уже есть качественные DOCX-шаблоны и нужны три понятных входа: ручная форма, таблица и JSON. Docmosis сильнее там, где требуется собственное размещение или сложная серверная интеграция. Plumsail Documents удобнее для сквозного процесса в Microsoft 365 с доставкой и подписью. PDFMonkey подходит разработчикам, которые предпочитают HTML/CSS и Liquid. Documint лучше для бизнес-пользователей, желающих собирать макет в визуальном редакторе, а не поддерживать Word-файл.

Как подготовить надёжный шаблон

• Используйте один набор разделителей во всём документе и не применяйте эти символы для обычного текста.
• Давайте полям стабильные имена без случайных пробелов; изменения согласовывайте с владельцем данных.
• Размещайте циклы внутри одной повторяемой строки таблицы или абзаца, чтобы не создавать пустые элементы.
• Передавайте расчётные суммы из исходной системы, если требуется строгое бухгалтерское округление.
• Тестируйте пустые значения, длинный текст, один и много элементов, перенос страницы и разные алфавиты.
• Храните исходный DOCX, пример данных и эталонный PDF вместе, чтобы быстро проверять обновления.

Тестовая запись должна быть намеренно сложнее обычной. В неё включают длинное название компании, адрес в несколько строк, максимальное число позиций, пустое необязательное поле, отрицательное или нулевое значение, изображение необычных пропорций и дату с часовым поясом. Если такой пример проходит без ошибок, повседневные документы будут устойчивее.

После каждого значимого изменения выполняют две проверки: визуальную и структурную. Визуальная подтверждает верстку, шрифты, таблицы и разрывы. Структурная сверяет число тегов, имена ключей, условия и форматы файлов. Только затем обновлённый шаблон подключают к массовой генерации.

Как выбрать источник данных

Источник	Когда использовать	Что проверить
Форма	Один договор, письмо или счёт, который вводит оператор	Заполнение обязательных по бизнес-правилам полей
Excel или CSV	Партия простых документов по строкам таблицы	Заголовки колонок, выбранный лист и типы данных
JSON	Вложенные объекты, массивы, интеграции и сложные отчёты	Массив верхнего уровня, синтаксис и совпадение ключей
API-интеграция	Автоматическая генерация из CRM, базы или приложения	Секреты, очередь, повторные попытки и журнал ошибок

Форма требует минимум подготовки, но плохо масштабируется. Таблица удобна бизнес-пользователям и хорошо видна перед запуском. JSON точнее передаёт реальную структуру данных, но требует технической дисциплины. API убирает ручные операции, однако ответственность за валидацию, доступы и повторные попытки переходит к интеграции.

Контроль качества готовых файлов

Для одиночного PDF достаточно открыть предпросмотр и проверить ключевые места: имя получателя, номер, дату, итог, таблицу и последнюю страницу. Для партии полезно выборочно открыть первый, средний и последний документ, а также экземпляры с минимальным и максимальным числом элементов.

При объединении проверяют границы между документами и разрывы страниц. При ZIP сверяют количество файлов с числом выбранных строк или объектов. Имя архива и имена вложенных файлов должны соответствовать правилам процесса и не содержать пустых фрагментов.

Отдельно проверяют шрифты и символы. Кириллица, латиница, знаки валют, длинное тире и специальные кавычки должны отображаться без квадратов и замен. Если используется пользовательский шрифт, тестируют все начертания: обычное, полужирное, курсив и их комбинации.

Для QR- и штрихкодов проводят реальное сканирование с печатной копии или экрана. Визуально правильный код может плохо читаться из-за малого размера, низкого контраста или слишком плотных данных. Проверка должна выполняться тем устройством, которое будет использоваться в работе.

Итоговая схема внедрения

1. Выберите один тип документа и подготовьте DOCX с постоянным текстом и тегами.
2. Загрузите шаблон, проверьте разделители и список распознанных полей.
3. Создайте тестовые данные с нормальными и граничными значениями.
4. Настройте формат, объединение, разрывы страниц, приложение и имена файлов.
5. Сравните готовый результат с утверждённым образцом и исправьте верстку.
6. Сохраните исходник, пример данных и эталонный файл, затем подключите интеграцию.
7. Добавьте очередь, повторные попытки, журнал ошибок и правила хранения.
8. После каждого изменения шаблона повторяйте контрольный тест.

DocuGenerate даёт наиболее предсказуемый результат, когда оформление остаётся в хорошо подготовленном Word-шаблоне, данные имеют стабильную структуру, а генерация проверяется на граничных примерах. В таком процессе один и тот же макет можно использовать для ручного документа, партии из таблицы и автоматического вызова API, не дублируя верстку и не перенося значения вручную.

Управление большой библиотекой шаблонов

Когда шаблонов становится много, одинаковые названия быстро перестают работать. В имени полезно отражать назначение и вариант документа: Счёт — услуги, Счёт — товары, Договор — предоплата, Договор — постоплата. В папках их группируют по процессу, а вложенные папки используют для страны, подразделения или языка. Такая структура сокращает риск выбрать похожий, но неверный макет.

Перед перемещением шаблона в папку следует проверить интеграции. Само распределение по папкам помогает навигации, однако автоматические сценарии обычно обращаются к идентификатору шаблона, а не к его позиции в интерфейсе. Идентификатор удобно записать в документацию процесса вместе с названием, ожидаемыми полями и контрольным примером данных.

Удаление папки и удаление шаблона — разные операции, поэтому перед очисткой нужно проверить, что происходит с вложенными элементами. Рабочий шаблон нельзя удалять только потому, что он не виден в текущем фильтре. Сначала снимают фильтрацию по папке, ищут по названию и сверяют идентификатор с настройками автоматизации.

Для каждого шаблона полезно назначить владельца. Этот человек отвечает за текст, набор тегов, эталонный результат и согласование изменений. Без владельца разные отделы могут загрузить несколько почти одинаковых файлов, а затем непонятно, какой из них используется в CRM. Один ответственный и короткий журнал изменений делают библиотеку управляемой.

Лимиты использования и планирование объёма

Документ учитывается по элементу данных. Если из ста строк Excel создаётся один объединённый PDF, расход всё равно равен ста документам. Если тот же набор выдаётся ZIP-архивом, расчёт не меняется. Поэтому объём следует оценивать по числу персонализированных экземпляров, а не по количеству файлов, которые пользователь видит после скачивания.

Бесплатный объём удобно использовать для тестирования нескольких шаблонов и проверки интеграции. Для реальной эксплуатации нужно учитывать месячное число счетов, договоров, сертификатов и повторных запусков. Ошибочная повторная генерация также расходует документы, поэтому перед большой партией стоит проверить одну запись и убедиться, что выбран правильный шаблон.

Месячное использование сбрасывается первого числа, а неиспользованный объём не переносится. В настройках можно отслеживать текущий расход и задать максимальный месячный предел, чтобы остановить генерацию после достижения установленного значения. Такой предел защищает от бесконечного цикла интеграции или неожиданно большого импорта.

Параллельный лимит и месячный объём решают разные задачи. Первый ограничивает число одновременно обрабатываемых операций, второй — общее количество созданных документов. Сценарий может иметь достаточный месячный запас, но получать временную ошибку из-за нескольких одновременных запросов. Очередь и повтор с задержкой устраняют временное ограничение, но не увеличивают месячный объём.

Пакетная операция уменьшает число одновременных запросов, однако не уменьшает расход документов. Её выбирают для удобства, последовательной обработки и единого результата. Если нужно немедленно вернуть файл каждому пользователю, лучше создавать отдельные задания через контролируемую очередь и учитывать максимальное время ожидания.

Многоязычные документы и локальные форматы

Для разных языков надёжнее использовать отдельные шаблоны, если меняется не только дата, но и юридический текст, порядок адреса, валюта и длина подписей. Один шаблон с множеством условий становится труднее проверять. Отдельные файлы позволяют редактору языка работать с обычным текстом Word и не затрагивать логику других вариантов.

Имена тегов можно оставить одинаковыми во всех языковых шаблонах. Тогда одна структура JSON подходит для русской, английской и немецкой версии, а интеграция выбирает нужный идентификатор шаблона. Такой подход отделяет содержание от данных и уменьшает количество преобразований в коде.

Дата должна приходить в устойчивом машинном виде, после чего фильтр формирует нужное представление. Для чисел следует заранее решить, где выполняется локализация: в источнике или в шаблоне. Смешивать готовые строки с запятыми и числовые выражения опасно, потому что строка может перестать участвовать в расчётах.

Шрифт обязан содержать все нужные символы. Для шаблонов с кириллицей, латиницей и диакритикой тестируют фамилии, адреса и названия городов из реальных стран. Если символ заменяется пустым квадратом, меняют шрифт либо подключают корректное начертание и повторно проверяют PDF.

Длина текста на разных языках отличается. Кнопки и короткие подписи в исходном макете могут стать длиннее, а юридический абзац — перейти на следующую страницу. Поэтому визуальную проверку проводят для каждого шаблона, даже если набор тегов полностью совпадает.

Безопасное изменение рабочего шаблона

Перед правкой скачивают используемый файл и сохраняют контрольный JSON. Затем в копии Word изменяют только нужный текст или оформление, не переименовывая теги без необходимости. После загрузки сравнивают список найденных полей со старым: пропавший или новый тег должен быть объяснён изменением задачи, а не случайной опечаткой.

Первый тест выполняют на одной записи с максимальным количеством заполненных полей. Проверяют первую страницу, таблицы, колонтитулы, последнюю страницу и приложение. Второй тест использует пустые необязательные значения, чтобы убедиться, что условия удаляют блоки без лишних пробелов.

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

При наличии истории версий можно восстановить предыдущий файл, однако данные и интеграция могли уже измениться. Откат шаблона не гарантирует совместимость с новым payload. Поэтому вместе с каждой значимой версией следует хранить пример данных и эталонный результат.

После изменения важно проверить не только визуальный PDF, но и другие используемые форматы. DOCX может выглядеть иначе после открытия в разных редакторах, а TXT теряет оформление. Если процесс выдаёт несколько форматов, контроль выполняют для каждого из них.

Проектирование устойчивой интеграции

Интеграция должна начинаться с валидации данных. До обращения к DocuGenerate проверяют обязательные ключи, типы чисел, допустимые даты, наличие элементов таблицы и доступность изображений. Ошибка на этом этапе возвращается пользователю быстрее и не расходует генерацию на заведомо неполный документ.

Каждому запросу присваивают внутренний идентификатор операции. Он связывает запись CRM, отправленный payload, ответ API и сохранённый файл. Если пользователь повторно нажмёт кнопку, система сможет определить, создавался ли документ уже, и не запустит неконтролируемый дубликат.

Для ожидания результата используют состояние задачи, а не постоянные частые запросы без задержки. Интервалы опроса увеличивают постепенно, учитывая, что PDF обычно готовится дольше DOCX, а пакет обрабатывается последовательно. После заданного тайм-аута задача переходит в состояние ошибки и ожидает решения оператора либо безопасной повторной попытки.

Повторять следует только временные ошибки: занятый параллельный слот, кратковременную сетевую проблему или недоступность сервиса. Ошибка шаблона, неверный API-ключ или некорректный JSON требуют исправления, а не автоматического повторения. Число попыток ограничивают, чтобы неисправная задача не расходовала ресурсы бесконечно.

Готовый файл сохраняют под уникальным именем и проверяют тип содержимого. Ссылка на загрузку не должна считаться успехом, пока приложение не получило файл и не записало его в целевое хранилище. Для бинарного ответа проверяют размер, расширение и возможность открыть документ.

Журнал должен содержать идентификатор шаблона, формат, число элементов, длительность и код результата. Персональные данные и API-ключ в журнал не помещают. Для диагностики достаточно безопасного идентификатора записи и описания шага, на котором произошла ошибка.

Практические вопросы о DocuGenerate

Можно ли создать один документ без Excel и JSON?

Да. Режим Fill out a form строит поля по тегам шаблона и позволяет ввести значения вручную. Для списков и таблиц элементы добавляются и удаляются прямо в форме. Этот режим рассчитан на один элемент данных.

Можно ли получить отдельный PDF для каждой строки Excel?

Да. После выбора строк в Merge options отключают объединение в один файл. Сервис создаёт ZIP, где каждой строке соответствует отдельный файл. В Advanced options можно задать динамическое имя с номером или другим тегом.

Можно ли объединить всю партию в один PDF?

Да. Включают Combine all documents in a single file и при необходимости Insert a page break after each document. Разрыв особенно важен для писем и счетов, чтобы новый экземпляр начинался с отдельной страницы.

Можно ли добавлять готовые условия или приложение?

Да, существующий PDF прикрепляется в Advanced options и добавляется в конец результата. Выходной формат при этом должен быть PDF. При раздельной партии одно и то же приложение добавляется к каждому экземпляру.

Почему DOCX нельзя посмотреть прямо в кабинете?

Встроенный просмотр предусмотрен для PDF. DOCX, DOC, ODT, TXT и ZIP загружают и открывают соответствующей программой. Если нужна быстрая визуальная проверка в интерфейсе, создают тестовый PDF.

Что произойдёт, если в данных нет поля для тега?

Тег заменится пустой строкой. Чтобы не получить незаполненный договор или счёт, обязательные значения проверяют до генерации. Для необязательного раздела используют условие, которое скрывает и подпись, и пустое значение.

Можно ли использовать вложенный JSON?

Да, после включения enhanced syntax к свойствам обращаются через точку, а массивы выводят циклами. Верхний уровень данных в интерфейсе всё равно должен быть массивом объектов, даже когда создаётся один документ.

Как избежать ошибки при недоступном логотипе?

Используют стабильный публичный URL, проверяют его до запуска или передают изображение Base64. Если загрузка по URL не удалась, изображение пропускается, поэтому критичный логотип нужно контролировать в готовом файле.

Как проверить шаблон перед большой партией?

Сначала создают один документ с граничными значениями, затем небольшую партию из нескольких разных записей. Проверяют число файлов, имена, разрывы страниц, таблицы, пустые поля и последнюю страницу. Только после этого запускают полный набор.

Заключение по рабочему процессу

DocuGenerate особенно эффективен в задачах, где внешний вид уже оформлен в Word, а переменные данные поступают из формы, таблицы, JSON или интеграции. Надёжность определяется не количеством настроек, а дисциплиной шаблона: стабильными тегами, корректными разделителями, тестовыми данными, понятными именами файлов, контролем очереди и проверкой готового результата. При таком подходе один макет обслуживает разовые документы и массовые партии без ручного копирования значений.