PDF Generator API помогает собирать счета, договоры, отчёты, этикетки и другие PDF из визуальных шаблонов и данных JSON: в редакторе можно расставить текст, таблицы, изображения, штрихкоды, QR-коды, диаграммы и поля подписи, а затем запускать выпуск документов через REST API, веб-форму или сценарий автоматизации.

Работа начинается в панели с разделами шаблонов, форм, хранилища документов, рабочих пространств и команды. Сам макет открывается на координатном полотне с линейками: слева находятся поля данных и компоненты, сверху — команды файла, вставки, форматирования и предварительного просмотра, справа — свойства выбранного объекта и расширенные параметры.

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

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

На стартовой панели основные задачи вынесены в отдельные карточки: создание динамического PDF, заполнение редактируемого PDF, создание нового шаблона, получение учётных данных API и настройка интеграции без кода. Такой вход удобен, когда пользователь ещё не знает, в каком разделе находится нужная команда. После первого запуска рабочая логика становится предсказуемой: макеты хранятся в Templates, пользовательские анкеты — в Forms, сгенерированные по ссылке документы — в Document Storage, а доступ конечных клиентов разделяется через Workspaces.

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

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

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

Редактор шаблонов и расположение инструментов

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

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

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

Компоненты можно располагать слоями. Если один объект перекрывает другой, контекстное меню содержит команды Bring to Front и Send to Back. Фиксация позиции предотвращает случайное смещение и отделяет объект от потока динамического содержимого. Это важно для печатных бланков: подпись, номер документа или метка должны оставаться на заданных координатах, даже если соседний текст становится длиннее.

Копия шаблона создаётся через File → Make a copy. Перед операцией необходимо сохранить изменения, потому что команда дублирует сохранённое состояние исходника, а не несохранённые правки на экране. Новая копия получает собственное имя, становится независимой и по умолчанию сохраняется как черновик с приватным доступом. Такой способ подходит для языковых вариантов, разных юридических лиц и документов с общей шапкой.

Подключение данных к шаблону

Основной формат входных данных — JSON. Поле шаблона обозначается фигурными скобками, например {customer_name}. При выпуске документа генератор ищет одноимённый ключ в объекте data и заменяет обозначение фактическим значением. Вложенные объекты позволяют сохранить естественную структуру: реквизиты клиента, адрес, сведения о заказе и строки счёта не приходится превращать в плоский список из сотен имён.

Тестовые данные добавляются двумя способами. В открытом редакторе используется Insert → Data, после чего можно выбрать локальный JSON, указать доступный адрес файла или вставить содержимое из буфера. Перед входом в шаблон доступен отдельный диалог, который принимает JSON, CSV и Excel; табличные форматы преобразуются в структуру данных. Кнопка Use Sample Data создаёт каркас по уже найденным полям шаблона, а Skip открывает макет без примера.

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

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

Имена полей чувствительны к структуре. Значение {customer::name} и плоский ключ {customer_name} — разные источники. При смене схемы данных шаблон не угадывает соответствие автоматически. Безопаснее утвердить контракт JSON, добавить тесты генерации и не переименовывать ключи без миграции макетов. Для временной совместимости можно создать вычисляемое поле или выражение, которое выбирает значение из старого либо нового ключа.

Текст, числа и даты

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

Текст умеет интерпретировать HTML-разметку, но при необходимости теги можно вывести как обычные символы. Параметр Compact HTML rendering убирает автоматические поля абзацев и уменьшает вертикальные зазоры. Отдельный HTML-компонент больше не добавляется в новые шаблоны: для такого содержимого используется усовершенствованный Text Component. Старые HTML-элементы продолжают выводиться, что позволяет не переделывать ранее созданные документы сразу.

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

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

Date Component отделяет входной формат от выходного. Это позволяет принять машинную дату и показать её в привычном виде, сменить часовой пояс или добавить дни. Если источник использует неоднозначную запись, входную маску следует указать явно. В противном случае значение вроде 03/04/2026 может быть понято как третье апреля или четвёртое марта. Для серверных процессов надёжнее передавать даты в ISO-представлении и форматировать только при выводе.

Таблицы и повторяющиеся блоки

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

У таблицы есть жёсткие ограничения. Ячейки не объединяются, их высота определяется содержимым, а изображения, QR-коды, флажки и вложенные компоненты внутри ячеек не поддерживаются. Если строка должна содержать фотографию товара или сложную карточку, вместо таблицы применяется Container Component. Контейнер представляет одну повторяемую запись и может включать текст, изображение, штрихкод, линию и другие элементы.

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

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

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

Изображения, штрихкоды и QR-коды

Image Component принимает локальный файл, статический общедоступный адрес, адрес из поля данных или строку base64. Поддерживаются комбинации статической части и динамического значения, что удобно для однотипных файлов в CDN. Для гарантированного вывода документация рекомендует PNG и JPG. Закрытый адрес, требующий cookie или авторизации, генератор прочитать не сможет; такой ресурс лучше передать в base64 либо разместить по временной подписанной ссылке.

Динамическая картинка должна содержать корректный тип. Для base64-строки требуется префикс вида data:image/..., иначе компонент не распознает формат. Если фото поворачивается неправильно из-за EXIF, полезно заранее нормализовать ориентацию или включить соответствующую обработку. Для больших изображений стоит уменьшить разрешение до фактического печатного размера: многомегапиксельный оригинал замедляет генерацию и увеличивает PDF без заметного выигрыша.

Barcode Component поддерживает линейные и двумерные форматы, включая варианты Code 39, Code 93, Code 128, GS1-128, EAN, UPC, фармацевтические коды, PDF417 и DataMatrix. Значение может быть статическим или приходить из JSON. В мелких этикетках разрешено выводить штрихкод как изображение вместо векторных линий: некоторые принтеры и сканеры стабильнее работают с таким вариантом. Перед массовой печатью образец нужно проверить тем же сканером и на том же материале.

QR Code Component кодирует текст или поле данных. Отдельный Assets API умеет создавать PNG-код, менять цвет и помещать логотип в центр, после чего ресурс сохраняется в библиотеке. В шаблоне следует оставлять тихую зону и достаточный контраст. Красивый цветной код с маленьким размером может перестать считываться после печати, сжатия или фотографирования, поэтому проверка должна включать реальный путь документа до пользователя.

Диаграммы и графическое представление данных

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

В свойствах меняются фон, цвет и размер шрифта, а выбор типа зависит от задачи. Горизонтальные столбцы удобны для длинных названий, линия — для временного ряда, круг — для небольшого количества долей, точечная диаграмма — для связи двух числовых показателей. Не стоит переносить в PDF интерактивную логику веб-дашборда: готовый документ статичен, поэтому подписи и легенда должны объяснять картину без наведения мыши.

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

Флажки, переключатели и подписи

Checkbox и Radio Button отображают логические состояния. Значение true или 1 отмечает элемент, false или 0 оставляет его пустым. В расширенных настройках компонент можно сделать редактируемым полем готового PDF. Тогда получатель меняет выбор уже после генерации. Для группы радиокнопок, где допустим только один вариант, элементы связываются через общий контекст данных, а при динамическом количестве вариантов удобно использовать контейнер.

Signature Field создаёт поле подписи PDF, которое можно открыть в совместимом просмотрщике, включая Adobe Reader. Это не то же самое, что нарисованная подпись в веб-просмотрщике: поле предназначено для последующего подписания средствами PDF-клиента. При проектировании юридического процесса нужно заранее решить, какой механизм требуется — визуальная подпись, криптографическая подпись в PDF или подтверждение ознакомления с журналом событий.

Встроенный Document Viewer поддерживает просмотр, подтверждение и рисование визуальной подписи. При выводе viewer API возвращает страницу, которую можно открыть или встроить в приложение. Для нескольких подписантов у компонента задаётся уникальный идентификатор, а в данных предварительного заполнения указывается signature_id. Тогда пользователь видит только назначенное ему поле и не может изменить подписи других сторон.

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

Колонтитулы, страницы и навигация

Header и Footer основаны на контейнере, занимают фиксированную область и повторяют вложенные компоненты на каждой странице. Внутрь можно поместить логотип, реквизиты, линию, текст и номер. Для нумерации используются поля {current_page} и {total_pages} либо специальная запись {page}/{total} в компоненте номера страницы. Если номер размещён вне колонтитула, автоматическое повторение не происходит.

Page Setup задаёт формат, ориентацию и поля. Отдельной странице можно назначить собственные параметры через контекстное меню, а общая команда File → Page Setup меняет страницы без индивидуальной настройки. Это позволяет поставить широкую таблицу в альбомной ориентации между портретными страницами. Сумма верхнего и нижнего полей не должна превышать 95 процентов высоты, а сумма левого и правого — 95 процентов ширины.

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

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

Выражения и условное форматирование

Expression Language выполняет математические и логические операции внутри шаблона. Выражение записывается в специальной конструкции и может складывать значения, сравнивать строки, выбирать вариант по условию, форматировать дату или собирать текст. Благодаря этому серверу не нужно заранее вычислять каждую печатную подпись. Однако сложную бизнес-логику лучше оставлять в приложении: шаблон должен отвечать за представление, а не становиться вторым расчётным модулем.

Для массивов доступны count, sum, avg, min, max, sumproduct, filter, iterate и join. Сочетание фильтра и итерации позволяет, например, посчитать сумму только по строкам определённой категории. Вложенные свойства в функциях обращаются через структуру объекта. Если поле иногда отсутствует, выражение должно учитывать пустое значение, иначе часть документов будет отличаться от тестового примера.

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

Conditional Formatting скрывает компонент или меняет его оформление. Несколько обычных условий соединяются по логике OR. Если формат должен применяться только при одновременном выполнении проверок, выбирается Expression и используется оператор AND. Таблицу нельзя скрыть напрямую тем же способом, поэтому её помещают внутрь контейнера и условие назначают контейнеру. Это характерный пример, когда знание модели компонентов важнее внешнего вида панели.

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

Предварительный просмотр и тестовая генерация

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

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

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

Аутентификация и первый запрос API

Все запросы защищаются JSON Web Token. Токен формируется на сервере приложения из ключа и секрета учётной записи, передаётся как Bearer Token и должен иметь ограниченное время жизни. Секрет нельзя помещать в JavaScript страницы, мобильное приложение или общедоступный репозиторий: любой пользователь сможет извлечь его и выпускать документы от имени организации. Клиентская часть должна обращаться к собственному серверу, а уже он — к API.

Для генерации используется запрос POST к пути /api/v4/documents/generate. В теле указывается объект шаблона с идентификатором и данными, желаемый формат, способ выдачи и имя. Минимальная схема выглядит как {"template":{"id":123,"data":{"name":"Иван"}}}. Фактический набор параметров лучше брать из актуальной спецификации и клиентской библиотеки, потому что строгая валидация отклоняет неизвестные или несовместимые значения.

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

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

Ответ может содержать base64, файл, временный адрес или ссылку на Viewer. Base64 удобно передать внутри JSON, но он увеличивает объём и память; поток файла экономичнее для прямой загрузки; адрес упрощает передачу между системами, но связан со сроком хранения; Viewer нужен для просмотра и подписания. Способ выдачи выбирают по следующему шагу, а не по привычке разработчика.

Хранилище документов и сроки доступа

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

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

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

Версии шаблонов и безопасная публикация

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

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

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

Веб-формы без разработки собственного интерфейса

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

Доступны текст, целое число, число с дробной частью, дата, подпись, раскрывающийся список, множественный выбор, таблица, изображение и PDF. Табличное поле создаёт массив объектов, который в шаблоне перебирается Table или Container Component. Изображение можно сразу показать в документе. Загруженный PDF передаётся в данных как base64 и не появляется в результирующем макете автоматически.

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

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

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

Импорт существующего PDF и заполнение форм

Статический PDF импортируется как неизменяемый фон. Это удобно для государственных бланков, сертификатов и фирменных форм, где положение печатных элементов уже утверждено. На фон накладываются динамические компоненты, а готовый PDF сохраняет выбираемый и корректно закодированный новый текст. Редактировать старую надпись, являющуюся частью фона, нельзя: её нужно изменить в исходном файле либо закрыть новым элементом, что не всегда приемлемо.

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

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

Преобразование HTML и страниц в PDF

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

URL-to-PDF принимает общедоступную страницу. Закрытый внутренний кабинет без доступной авторизации сервис не откроет обычным адресом. Страница должна успеть загрузить данные и ресурсы, а печатные стили — учитывать фиксированный размер листа. Для сложного одностраничного приложения надёжнее передать готовый HTML или сформировать данные на сервере, чем зависеть от клиентского JavaScript и состояния браузера.

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

HTML-режим и визуальный редактор решают разные задачи. HTML даёт разработчику полный контроль над CSS, визуальный шаблон позволяет сотруднику менять расположение без правки кода. В одном проекте можно использовать оба пути: счета собирать в редакторе, а сложные публикации с готовой веб-вёрсткой — через HTML-to-PDF.

Дополнительные операции с PDF

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

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

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

PDF-to-Image создаёт изображения страниц, что полезно для миниатюр, предварительного просмотра и проверки содержимого. Для многостраничного файла возвращается отдельное изображение на страницу. Этот endpoint не заменяет извлечение текста и не превращает скан в редактируемый документ; он только визуализирует страницы.

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

Рабочие пространства, роли и встраивание

Workspace изолирует шаблоны конкретного пользователя или клиента. Главный пользователь управляет организацией, несколькими рабочими областями и общими шаблонами. Обычный пользователь ограничен своей областью и открывает редактор через API. Такая модель позволяет встроить конструктор в SaaS-продукт: клиент видит собственные документы, не получает доступ к чужим макетам и не обязан входить в отдельную административную панель.

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

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

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

Интеграции и автоматизация

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

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

Airtable и Adalo имеют специализированные способы подключения. В Adalo компонент содержит разделы учётных данных, строк массива и кнопки; результат можно подставить в действие External Link. Учетные данные при этом нельзя помещать в публичный экран без защиты. В Airtable расширение использует записи таблицы и выбранное представление, что удобно для документов по строкам базы.

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

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

Шрифты, языки и направление текста

В редакторе есть гарнитуры для латиницы, кириллицы, греческого, иврита, арабского, деванагари, тайского, китайского, японского и корейского письма. Среди них Arimo, DejaVu Sans, Montserrat, Open Sans, Cairo, M+ Japanese, Nanum Gothic, SimHei, Source Han Sans и Source Han Serif. Поддержка зависит от конкретного шрифта: наличие языка в данных не означает, что выбранная гарнитура содержит нужные знаки.

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

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

Font subsetting уменьшает файл, включая только использованные знаки, но влияет на время генерации и совместимость с архивным профилем. Если документ должен соответствовать PDF/A, настройку нельзя включать без проверки валидатором. Оптимальный режим выбирают по назначению: архив, печать, отправка по почте и веб-просмотр предъявляют разные требования.

Доступность документов

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

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

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

Практические сценарии

Счета и коммерческие документы

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

Упаковочные листы и этикетки

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

Договоры и предложения

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

Анкеты KYC и заявки

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

Отчёты и сертификаты

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

Электронные счета и архивные форматы

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

Ошибки API и способы диагностики

Ответ 401 обычно указывает на отсутствующий, просроченный или неверно подписанный JWT. Проверяют ключ, секрет, время сервера, алгоритм и заголовок Authorization. Токен не следует кэшировать дольше его срока. Если ошибка возникает только в одном окружении, сравнивают часы сервера и набор секретов, а не создают бессрочный токен.

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

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

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

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

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

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

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

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

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

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

Контроль качества перед массовым запуском

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

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

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

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

Безопасность и обращение с данными

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

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

Временное хранилище удобно для доставки, но политика организации может требовать более короткий срок. Настройка retention позволяет уменьшить период, а постоянная копия переносится в контролируемое хранилище. Если используется Viewer, удаление нельзя выполнять до завершения процесса подписания и получения webhook.

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

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

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

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

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

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

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

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

Форматы вывода, расход ресурсов и производительность

Формат результата выбирается под назначение документа. Обычный PDF подходит для просмотра и печати, архивный профиль нужен для длительного хранения, доступный профиль — для корректной работы средств чтения с экрана, а HTML или XLSX применяются в тех сценариях, где последующая обработка важнее неизменяемой страницы. Наличие формата в параметрах не освобождает от проверки: вложенный шрифт, прозрачность, интерактивное поле или неверная структура могут нарушить требования конкретного стандарта.

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

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

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

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

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

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

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

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

Электронные счета и структурированные вложения

Электронный счёт отличается от обычного PDF тем, что получателю нужны не только видимые строки, но и машиночитаемые данные. Поддерживаемые сценарии включают UBL, CII, XRechnung, Factur-X и ZUGFeRD. В гибридном варианте визуальная страница объединяется со структурированным XML, который бухгалтерская система может извлечь и проверить. Дизайн не должен противоречить данным вложения: суммы, налоги, валюта и реквизиты обязаны совпадать.

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

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

Наблюдаемость и сопровождение интеграции

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

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

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

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

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

Сравнение PDF Generator API с аналогами

Программа	Лучше подходит для	Главное ограничение
PDF Generator API	Визуальных шаблонов, JSON-данных, форм, рабочих пространств и полного цикла просмотра	Для автоматизации нужна серверная настройка и понимание структуры данных
PDF Commander	Ручного редактирования, сборки и исправления отдельных PDF пользователем	Нет REST-механизма массовой генерации из JSON-шаблонов
PDFMonkey	Разработчиков, предпочитающих HTML, CSS и Liquid-шаблоны	Точная вёрстка сильнее зависит от навыков веб-разработки
DocRaptor	Сложного HTML-to-PDF с CSS Paged Media, формами и типографикой Prince	Не ориентирован на визуальный координатный редактор бизнес-шаблонов
APITemplate.io	Генерации PDF и изображений через визуальные или HTML-шаблоны	Расширенный набор двух типов контента добавляет больше вариантов настройки
Anvil PDF Generation API	Преобразования HTML, CSS или Markdown и заполнения готовых PDF-форм	Основной путь генерации требует подготовленной разметки

PDF Generator API стоит выбирать, когда макет должны менять не только разработчики, данные приходят в JSON, а продукту нужны рабочие пространства, формы, просмотр, подпись и аудит. PDF Commander удобнее для разовой ручной правки файла. PDFMonkey подходит команде с опытом HTML и Liquid, DocRaptor — для сложной печатной CSS-вёрстки, APITemplate.io — когда вместе с PDF выпускаются изображения, а Anvil — когда исходником служат HTML, Markdown или существующие поля PDF.

Как выбрать подход к внедрению

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

Затем выбирают способ ввода. Данные из приложения идут через API, данные от конечного пользователя — через Web Form, данные из no-code процесса — через Make, Zapier или n8n. Эти пути можно комбинировать: форма собирает сведения, API дополняет их из CRM, а Viewer получает итог на подпись.

Третий вопрос — доставка. Для немедленной загрузки подходит файл или base64, для короткой передачи между системами — временный адрес, для согласования — Viewer. Для архива результат всегда переносится в собственное хранилище. Выбор следует оформить как часть архитектуры, чтобы разные команды не использовали несовместимые схемы.

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

Итоговый порядок настройки

1. Описать JSON-схему и подготовить обезличенные наборы для короткого, обычного и максимального документа.
2. Выбрать галерею, чистый лист, импорт статического PDF, импорт редактируемой формы или HTML-преобразование.
3. Разместить компоненты, назначить поля данных, проверить числа, даты, массивы и условные правила.
4. Настроить страницы, колонтитулы, шрифты, направление текста, заголовочную структуру и альтернативные описания.
5. Сгенерировать Preview на всех тестовых наборах, проверить переносы, коды, подписи и многостраничные таблицы.
6. Создать серверный JWT, закрепить workspace и выполнить запрос с подходящим способом выдачи.
7. Подключить формы, Viewer, webhook и хранилище только после стабильной базовой генерации.
8. Назначить проверенную версию Production, включить мониторинг ошибок, времени и размера документов.

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