В Docamatic можно автоматически собирать PDF из HTML и CSS, заполнять готовые шаблоны данными JSON, превращать страницы в PNG, WEBP или JPG, дописывать текст, изображения, штрихкоды и QR-коды в существующие PDF, объединять файлы и защищать результат паролем. Основная работа строится вокруг HTTPS-запросов к REST API, а панели Documents, Logs и Webhooks помогают находить созданные документы, контролировать расход квоты и разбирать ошибки интеграции.

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

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

Панель управления и логика рабочего процесса

Главный экран Docamatic рассчитан не на ручное редактирование страниц, а на наблюдение за потоком автоматических операций. Слева и справа расположены индикаторы Production Usage и Test Usage: такое разделение позволяет проверять шаблоны и параметры без смешения с боевой квотой. Ниже график Documents Created показывает динамику за выбранный интервал, а круговая диаграмма Requests By Endpoint помогает быстро заметить, какой сценарий создаёт основную нагрузку — HTML в PDF, шаблоны, изображения, запись поверх PDF или шифрование.

В таблице Latest Documents полезны сразу несколько полей. TYPE показывает формат результата, NAME — значение параметра name, SIZE помогает обнаружить неожиданно тяжёлые документы, ENV различает тестовую и производственную среду, CREATED фиксирует момент обработки, а EXPIRES напоминает, когда временная ссылка перестанет работать. При отладке это позволяет отвечать не только на вопрос создался ли файл, но и на вопросы какой именно запрос его создал, не попал ли он в тестовый режим и успеет ли получатель открыть ссылку до удаления.

Раздел Documents подходит для проверки результата и срока хранения, Logs — для анализа технических ответов, Webhooks — для контроля обратных вызовов. Практически это задаёт удобную последовательность диагностики. Сначала ищут запись по transaction_id или имени, затем проверяют код ответа и размер, после этого смотрят, был ли отправлен webhook и какой статус вернул принимающий сервер. Такой порядок помогает отделить ошибку рендеринга от ошибки доставки уведомления.

Параметр name стоит заполнять осмысленно. Вместо случайного UUID в имени полезно использовать тип документа и внутренний номер, например invoice-5412 или shipping-label-20401. Это не заменяет transaction_id, но делает список документов читаемым для сотрудника, который не видит журнал приложения. При этом конфиденциальные данные, полные адреса и номера карт в name лучше не помещать: имя отображается в административной части и может попадать в служебные снимки экрана.

Авторизация и первый запрос

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

Минимальный запрос к конечной точке PDF содержит только source. Источником может быть полный HTML или доступная для обработчика страница. Для первого теста безопаснее отправить короткую HTML-строку: так исключаются ошибки DNS, авторизации стороннего сайта, блокировки ресурсов и нестабильного JavaScript. Когда базовый ответ получен, к запросу по одному добавляют формат бумаги, поля, медиарежим и остальные параметры.

POST /api/v1/pdf
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "source": "<html><body><h1>Счёт № 5412</h1><p>К оплате: 12 400 ₽</p></body></html>",
  "format": "A4",
  "media": "print",
  "test": true,
  "name": "invoice-5412"
}

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

Успешный JSON обычно содержит document, size, success и transaction_id. Поле document может быть временной ссылкой или строкой base64 — это зависит от encode и размера результата. Приложение должно проверять не только HTTP 200, но и success, сохранять transaction_id в журнале и валидировать ожидаемый формат. Если вместо PDF пришёл текст ошибки, слепая запись тела ответа в файл создаст документ, который не откроется.

Как строить обработчик ответа

Надёжный обработчик разделяет транспортную ошибку и ошибку задания. При сетевом тайм-ауте запрос можно повторить с тем же внутренним идентификатором, но до повтора важно проверить, не был ли документ создан: иначе пользователь получит дубликат, а квота будет списана дважды. При кодах 400, 415 или 422 автоматический повтор без изменения данных бессмысленен. При 429 требуется пауза, а при 500 допустим повтор с увеличивающимся интервалом.

• Сначала проверить HTTP-код и возможность разобрать JSON.
• Затем проверить success и наличие transaction_id.
• Если encode включён, определить, действительно ли document содержит base64, а не ссылку из-за превышения 4 МБ.
• Проверить Content-Type и сигнатуру готового файла до передачи пользователю.
• Записать размер, имя операции и transaction_id в журнал без API-ключа и персональных данных.

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

Генерация PDF из HTML и CSS

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

Параметр media принимает screen или print. Если в стилях есть правила @media print, для деловых документов обычно выбирают print: можно скрыть кнопки, навигацию, поля ввода и интерактивные панели, а также задать печатные размеры. Screen полезен, когда PDF должен повторять внешний вид страницы на экране. Несоответствие media — частая причина пропавших блоков или лишних элементов.

Размер листа задают параметром format либо парой width и height. Готовые значения включают Letter, Legal, Tabloid, Ledger и диапазон A0–A5. Если format передан одновременно с width и height, приоритет имеет format. Для нестандартной этикетки или бейджа используют width, height и unit; единицы могут быть px, in, cm или mm. Ориентацию меняет landscape.

Поля margin_top, margin_right, margin_bottom и margin_left работают вместе с margin_unit. Когда единица явно не указана, нельзя полагаться на догадку при переносе конфигурации между проектами; лучше всегда передавать margin_unit. Слишком большие поля уменьшают полезную область и могут перенести таблицу на следующую страницу, а нулевые поля иногда выводят содержимое в непечатаемую зону при дальнейшей физической печати.

Параметр prefer_css_page_size отдаёт приоритет размеру из CSS @page. Он нужен, когда шаблон сам определяет лист и ориентацию. Без него содержимое может масштабироваться под format, width или height из JSON. Если документ неожиданно уменьшился или стал обрезаться, следует проверить конфликт между @page и параметрами запроса и оставить только один источник истины.

{
  "source": "<html><head><style>@page { size: A4; margin: 14mm; } body { font-family: Arial; }</style></head><body>...</body></html>",
  "media": "print",
  "prefer_css_page_size": true,
  "page_numbers": true,
  "test": true
}

Масштаб zoom принимает значения от 0,1 до 2 и по умолчанию равен 1. Его не стоит использовать как постоянную замену корректной вёрстке: уменьшение скрывает переполнение, но делает шрифт мелким; увеличение может обрезать таблицы и изображения. Zoom полезен как точечная настройка для уже стабильного макета, например когда исходная страница рассчитана на чуть более широкий экран.

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

Колонтитулы, номера и диапазоны страниц

Для простой нумерации достаточно page_numbers. Если нужен собственный футер, используют footer_template с HTML. В шаблоне доступны классы date, title, url, pageNumber и totalPages, в которые подставляются значения печати. Аналогично работает header_template. Когда footer_template задан, автоматический page_numbers игнорируется, поэтому номер страницы следует добавить в собственный шаблон явно.

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

Параметр page_ranges позволяет печатать не весь результат, а выбранные страницы, например 1–5, 8 и 11–13. Это удобно для выборочного приложения к договору или повторной выдачи повреждённого листа. Диапазон применяется после формирования раскладки, поэтому изменение данных или стилей может сдвинуть нужный раздел на другую страницу. Номер нельзя хранить как постоянный атрибут смыслового блока без проверки итоговой пагинации.

Подключение CSS, авторизация страницы и элементы согласия

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

Если source указывает на страницу с базовой HTTP-аутентификацией, объект auth принимает username и password. Это не форма входа и не обработка сложного корпоративного SSO; параметр предназначен именно для Basic Auth. Учётные данные нужно передавать из секрет-хранилища, а не сохранять в шаблоне или журнале. После теста следует убедиться, что в логах приложения не остаётся полный JSON запроса.

Для страниц с баннером согласия существует accept_cookie_warning. Автоматическое принятие работает не для каждого варианта разметки, поэтому предусмотрен click_elements: массив может содержать текст кнопки или CSS-класс элемента. Эта функция полезна не только для cookie-баннера, но и для раскрытия вкладки или нажатия кнопки перед печатью. Выбор должен быть однозначным; общий текст вроде Открыть способен нажать не тот элемент после изменения страницы.

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

Получение результата: ссылка, base64 и хранение

По умолчанию результат возвращается как ссылка на временный объект. При encode=true сервис пытается вернуть содержимое в base64. Для файлов больше 4 МБ действует практическое ограничение: вместо base64 возвращается URL. Поэтому код не должен считать любое значение document закодированными байтами только потому, что encode был передан. Перед декодированием нужно проверить структуру строки и обработать вариант со ссылкой.

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

Временная ссылка подходит для короткой выдачи, но её срок нельзя путать с бизнес-сроком хранения документа. На бесплатном плане файл может храниться до 48 часов, на платном — до 14 дней в зависимости от настройки. Договор, счёт или сертификат, который должен быть доступен месяцами, следует сразу перенести в систему документов организации и хранить там согласно внутренним правилам.

Через объект s3 можно сохранить результат напрямую в свой Amazon S3 bucket. Указываются region, bucket и при необходимости path. Перед использованием меняют политику корзины, предоставляя Docamatic право записи. Разрешение следует ограничить нужной корзиной и префиксом, а после настройки проверить, что сервис не может читать или удалять лишние объекты. В панели доступен пример политики, но его всё равно нужно сверить с моделью доступа организации.

Если документ возвращён в base64, он не сохраняется во временном хранилище Docamatic. Если используется ссылка, срок задаётся в настройках, а досрочное удаление выполняется конечной точкой delete по transaction_id. Удаление полезно после подтверждённого копирования в собственное хранилище. Сначала следует проверить контрольную сумму или хотя бы размер загруженного файла, и только затем удалять оригинал, иначе сбой передачи оставит систему без единственной копии.

Шаблоны JSON для счетов, этикеток и форм

Template API избавляет от самостоятельной вёрстки, когда подходит один из готовых макетов. Запрос содержит имя template и объект data. Доступны шаблоны счетов, packing slip, формы возврата, коммерческого инвойса, коммерческого предложения, транспортных этикеток 4×6 и 4×3, этикеток со штрихкодом и QR-кодом, а также бейджа конференции. Каждый шаблон имеет собственный набор полей, поэтому объект data нельзя без проверки переносить из одного макета в другой.

Общие параметры позволяют выбрать PDF, PNG, WEBP или JPG, задать формат, размеры, ориентацию, качество, оттенки серого, нумерацию, имя и шрифт. Для фиксированных шаблонов размер может быть задан самим макетом; тогда format, width и height игнорируются. Это особенно важно для этикеток: попытка принудительно сделать их A4 не растянет композицию ожидаемым образом.

В шаблоне invoice1 поля разделены на реквизиты заказа, адреса Bill to и Ship to, строки товаров, скидку, доставку, налог, итог, примечание и сведения о компании. В строке товара можно передать изображение, описание, SKU, штрихкод, количество, исходную цену, фактическую цену и сумму. Логотип, подписи полей и даже текст благодарности приходят из data, поэтому один макет можно использовать для нескольких брендов и языков, если все подписи подготовлены приложением.

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

invoice5 рассчитан на компактный счёт за услуги: в нём есть крупный итог, строки работ, реквизиты From и To и две кнопки оплаты с текстом, адресом и SVG-значком. Ссылки в итоговом PDF следует формировать только из доверенных доменов. Нельзя подставлять произвольный адрес из запроса клиента, иначе официальный счёт станет носителем фишинговой кнопки.

Коммерческие предложения и экспортные документы

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

commercial_invoice предназначен для международной отгрузки и включает экспортёра, получателя, возможного покупателя, страны, причину экспорта, позиции с HS code, единицей измерения, количеством, весом и стоимостью, а также число мест, общий вес, валюту, Incoterm и подпись. Макет помогает собрать структуру, но не проверяет таможенную классификацию. Код HS, EORI, Incoterm и стоимость должны поступать из проверенной системы учёта.

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

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

packing_slip1 содержит номер заказа, дату, перевозчика, трек-номер, количество позиций, адреса, изображения товаров, SKU, штрихкоды и примечание. В отличие от счёта, цены здесь не обязательны: документ ориентирован на комплектование и проверку содержимого. Внутренний процесс может создавать packing slip после резервирования товара, а счёт — после оплаты, не смешивая разные статусы заказа.

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

shipping_label_4x6 рассчитан на адрес, отправителя, номер заказа, ссылочный номер, вес, штрихкод и инструкцию доставки. Размер 4×6 подходит распространённым термопринтерам, но реальную печать нужно проверять без масштабирования: драйвер не должен автоматически вписывать этикетку в другой лист. Штрихкод тестируют сканером после печати, потому что визуально ровные полосы могут потерять читаемость из-за низкого разрешения или термоголовки.

Отдельные barcode_label и qr_label используют размеры 4×3 дюйма, заголовок, подзаголовок, код и подпись. Значение штрихкода следует проверять на допустимые символы выбранной символогии, а QR-код — на длину и контраст. Для длинных адресов QR становится плотнее; при маленькой печати это снижает запас распознавания. Перед массовым выпуском стоит напечатать крайние примеры: самый короткий и самый длинный код.

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

Настройка внешнего вида готовых шаблонов

Параметр font указывает шрифт Google по точному названию, font_size принимает коэффициент от 0,5 до 1,4, font_color — шестнадцатеричный цвет. В data многие шаблоны дополнительно принимают основной и акцентный цвет. Эти настройки удобны для брендирования, но не заменяют полноценный дизайн: расположение блоков остаётся заданным. Если требуется переставить колонки, добавить новый раздел или изменить алгоритм переноса, проще перейти на собственный HTML.

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

file_type позволяет получить не только PDF, но и PNG, WEBP или JPG. Изображение удобно для превью, вложения в чат или печати этикетки там, где обработка PDF затруднена. Но многостраничный документ логичнее хранить в PDF: растровый формат увеличивает размер, теряет поиск по тексту и требует отдельного соглашения о представлении каждой страницы.

Создание скриншотов страниц и HTML

Конечная точка image принимает source и создаёт PNG, WEBP или JPG. Можно задать ширину, высоту и единицы, учитывать мобильный viewport, включить landscape, снять всю прокручиваемую страницу, обрезать область, изменить качество, перевести результат в оттенки серого и внедрить CSS. Это подходит для превью страниц, карточек отчёта, визуальных снимков состояния и генерации изображений из HTML-макета.

full_page захватывает всю высоту страницы, а clip — только прямоугольник с координатами x, y, width и height. Эти режимы решают разные задачи. Полная страница полезна для архива или проверки длинной публикации; clip — для диаграммы, ценового блока или конкретной карточки. Если макет адаптивный, координаты clip следует рассчитывать для фиксированной ширины, иначе изменение переноса сдвинет область.

quality принимает значения от 1 до 3. Повышение качества увеличивает разрешение и размер файла. Для миниатюры в списке обычно достаточно базового уровня; для печатной этикетки или распознавания мелкого текста потребуется более высокий. Нельзя выбирать максимальное значение по умолчанию для каждого снимка: оно увеличит время передачи и расход памяти без пользы для маленьких превью.

Параметр mobile определяет, учитывается ли meta viewport. В сочетании с width и height он помогает воспроизвести мобильную компоновку. Landscape меняет ориентацию viewport. Для регрессионных снимков важно фиксировать все параметры, а не только source: иначе два запуска одной страницы могут отличаться потому, что использовали разные размеры и медиарежим.

Как и в PDF-сценарии, доступны css, accept_cookie_warning, click_elements, auth, webhook, encode, name и s3. Это позволяет скрыть персонализированные элементы, раскрыть нужную вкладку, пройти Basic Auth и сразу сохранить изображение в своей корзине. При съёмке сторонних страниц следует учитывать право на использование содержимого и не передавать секретные данные в URL.

Добавление элементов в существующий PDF

Write to PDF API берёт существующий PDF из URL или base64 и размещает поверх него текст, текстовые ячейки, изображения, штрихкоды и QR-коды. Координаты задаются в миллиметрах, а для каждого элемента можно указать номер страницы. Такой механизм подходит для заполнения подготовленного бланка, нанесения адреса на этикетку, персонализации сертификата, добавления водяного знака или кода отслеживания.

Для текста используются text_value, text_color, font, font_size, font_style, text_x, text_y и text_page_number. Поддерживаются Arial, Courier, Helvetica, Times, PassionsConflict и ArchivoBlack; стили обозначаются B, I и U. Если номер страницы не передан, элемент может быть добавлен на все страницы, что полезно для водяного знака, но опасно для адреса или подписи. Номер следует задавать явно, когда повторение не требуется.

Объект cells предназначен для текста с переносами и выравниванием. Помимо координат он принимает width, обязательную height, align и border. Выравнивание может быть левым, центральным, правым или по ширине. Ячейка удобнее простого текста для длинного адреса и комментария, но высоту нужно выбирать с запасом: API не может угадать, должен ли лишний текст уменьшиться, обрезаться или выйти за рамку бизнес-бланка.

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

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

POST /api/v1/write
{
  "source": "BASE64_PDF",
  "text": [{
    "text_value": "Иван Петров",
    "font": "Arial",
    "font_size": 18,
    "font_style": "B",
    "text_x": 38,
    "text_y": 72,
    "text_page_number": 1
  }],
  "qr_codes": [{
    "qr_code_value": "CERT-2026-00418",
    "qr_code_x": 150,
    "qr_code_y": 210,
    "qr_code_size": 24,
    "qr_code_page_number": 1
  }],
  "test": true
}

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

Объединение PDF

Конечная точка merge принимает массив files. Каждый элемент может быть ссылкой на PDF или строкой base64. Порядок массива определяет порядок частей в итоговом документе. Это позволяет собрать пакет из счёта, условий, приложения и подтверждения либо объединить несколько отчётов одного периода.

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

В merge доступны test, encode, webhook, name и s3. Для длинных пакетов лучше использовать webhook или прямую запись в S3, а не удерживать пользовательский HTTP-запрос до завершения. Приложение может показать статус формируется, сохранить идентификатор задания и выдать файл после обратного вызова.

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

Защита PDF паролем

Конечная точка encrypt устанавливает пароль на существующий PDF. Источник передаётся как URL или base64, password задаёт пароль, encryption — AES_128 или AES_256. По умолчанию используется 256-битное AES. Для тестового документа пароль принудительно становится docamatic_sample, поэтому тест нельзя использовать для проверки реальной политики секретов.

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

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

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

Webhooks и асинхронная обработка

Если в запросе задан webhook, Docamatic отправляет POST после генерации. В JSON обратного вызова присутствуют ссылка на документ и transaction_id. Принимающий адрес должен вернуть HTTP 200. Webhook полезен для тяжёлых документов и потоков, где пользователь не должен ждать открытого соединения.

Обработчик webhook обязан быть идемпотентным. Один и тот же transaction_id нельзя превращать в два письма, две записи оплаты или два уведомления. В базе создают уникальное ограничение по идентификатору, а повторный callback подтверждают кодом 200 после проверки, что результат уже обработан.

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

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

Автоматизация через Zapier

Интеграция с Zapier позволяет строить процессы без собственного HTTP-кода: строка в таблице, входящее письмо или событие другой системы запускает действие Docamatic, а созданный документ передаётся в хранилище, почту или следующий шаг. Это подходит для небольших потоков счетов, packing slip, изображений страниц и документов по готовому шаблону.

В Zapier доступны действия конвертации URL или HTML в изображение, создания PDF и триггер нового документа. Практический сценарий: новая строка Google Sheets содержит реквизиты, Zap формирует объект данных, Docamatic создаёт PDF по шаблону, следующий шаг сохраняет его в облачную папку и отправляет ответственному сотруднику.

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

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

Квоты, лимиты и контроль расхода

Бесплатный план предоставляет 30 документов или изображений в месяц. Успешные производственные POST-запросы, создающие документ или изображение, расходуют квоту; тестовые операции предназначены для разработки. Платные планы увеличивают месячный объём, а для некоторых уровней доступны собственный S3 и webhooks. Перед внедрением нужно сверить требуемые возможности, а не только число документов.

Панель показывает Production Usage и Test Usage, а конечная точка credits возвращает limit, used и remaining для обеих категорий вместе с началом и концом расчётного периода. Приложение может опрашивать credits по расписанию и предупреждать администратора до исчерпания лимита. На стороне сервиса также предусмотрены уведомления при достижении 50, 75, 80 и 95 процентов месячного объёма.

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

Защитой от циклической ошибки служат собственные лимиты. На один заказ разрешают фиксированное число попыток, на один шаблон — разумный суточный объём, а резкий рост запросов вызывает сигнал. Transaction_id и внутренний idempotency key помогают увидеть, что приложение генерирует один и тот же документ снова и снова.

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

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

Счета и квитанции

Для счёта данные берут из системы заказов, рассчитывают суммы и налог, затем выбирают готовый invoice или собственный HTML. В запросе задают имя с номером заказа и test на этапе проверки. После успешного боевого ответа PDF сохраняют в архив организации, transaction_id записывают в заказ, а клиенту отправляют постоянную ссылку из собственного хранилища, а не временный адрес.

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

Транспортные документы и склад

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

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

Сертификаты и персонализированные бланки

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

QR-код может содержать короткий непрогнозируемый идентификатор, по которому система проверки показывает статус сертификата. Не стоит помещать в код полные персональные данные. Это уменьшает плотность QR и не раскрывает информацию любому сканирующему приложению.

Отчёты и диаграммы

Отчёт обычно проще создавать из HTML: сервер формирует таблицы, диаграммы и текст, а Docamatic отвечает за печатный PDF. Для предсказуемого результата задают print CSS, A4, поля, разрывы перед крупными разделами и повторяющийся заголовок таблицы. Большие графики проверяют в цвете и grayscale, если часть получателей печатает на чёрно-белом устройстве.

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

Снимки страниц и визуальный контроль

Screenshot API можно применять для сохранения состояния публичной страницы или генерации карточек из HTML. Для контроля интерфейса фиксируют viewport, media, mobile, injected CSS и список нажатий. Иначе различия между снимками будут вызваны конфигурацией, а не изменением страницы.

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

Ошибки API и способы устранения

Код 400 означает некорректный запрос. Следует проверить обязательный source, типы полей, допустимые значения format, media и unit, а также структуру вложенных объектов. Логировать весь документ с персональными данными не нужно; достаточно безопасного набора параметров и сообщения ответа.

401 указывает на отсутствие разрешения, 403 — на неаутентифицированный запрос. На практике проверяют, передан ли заголовок Authorization, начинается ли он с Bearer, не содержит ли ключ пробелы или перенос строки и относится ли он к нужному аккаунту. Ключ не выводят в сообщение об ошибке и не отправляют пользователю интерфейса.

405 возникает при неправильном HTTP-методе. Большинство операций генерации используют POST, delete — DELETE, credits — GET. Прокси, no-code коннектор или универсальная библиотека могут незаметно отправить GET вместо POST после редиректа. В журнале следует сохранять фактический метод и путь.

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

415 указывает, что тело не является корректным JSON или имеет неверный Content-Type. Нужно отправлять application/json и сериализованный объект, а не строковое представление словаря языка программирования. Особое внимание — кавычкам внутри HTML: библиотека JSON должна экранировать их автоматически.

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

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

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

Пустой, обрезанный или неправильно оформленный PDF

Пустой файл чаще всего связан с тем, что source вернул страницу входа, данные загружались поздним JavaScript или print CSS скрывает содержимое. Проверяют исходный HTML, медиарежим и доступность ресурсов. Для защищённой страницы используют auth только при Basic Auth; сложную сессию надёжнее заменить передачей готового HTML.

Обрезанные таблицы указывают на конфликт ширины, масштабирования и фиксированных размеров. Проверяют format, width, height, unit, landscape, zoom и prefer_css_page_size. В CSS убирают жёсткую ширину, добавляют перенос длинных слов и адаптируют таблицу к печати. Уменьшение zoom используют последним, потому что оно ухудшает читаемость всего документа.

Пропавший фон связан с disable_backgrounds или печатными стилями. Неверные цвета могут возникнуть после grayscale. Отсутствующая нумерация — из-за собственного footer_template, который отключил page_numbers. Каждую настройку следует проверять в минимальном документе, чтобы не путать поведение API и сложность шаблона.

Проблемы с изображениями и шрифтами

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

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

Безопасность документов и ключей

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

В журнале разрешено хранить transaction_id, endpoint, безопасное имя, размер, статус и время. Полный HTML счёта, адреса клиентов, пароли PDF и API-ключи следует исключить или маскировать. Отладочный режим, который печатает весь запрос, нужно отключать до запуска с реальными данными.

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

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

Для чувствительных PDF можно запросить base64, сразу сохранить файл в защищённой системе и не сохранять его у Docamatic. Ограничение 4 МБ требует предусмотреть запасной путь через URL или S3. Решение должно быть протестировано на максимальном ожидаемом документе, а не только на одностраничном примере.

Подготовка интеграции к эксплуатации

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

Шаблоны и параметры нужно версионировать вместе с кодом. Изменение CSS, логотипа, font_size или координат write создаёт новую ревизию. В заказе или отчёте сохраняют номер ревизии, чтобы позже объяснить, почему два документа одного типа выглядят по-разному.

Автоматические тесты могут генерировать документы с test=true и проверять HTTP-код, success, формат, размер и наличие ключевых строк после извлечения текста. Визуальные тесты сравнивают изображения страниц с допуском, потому что мелкие различия рендеринга возможны. Критичные зоны — итог, номер, адрес, подпись и штрихкод — проверяют отдельно.

Нагрузочный тест должен учитывать лимит 120 запросов в минуту. Цель — проверить очередь, повторы и webhook, а не намеренно создать отказ. Производственные кредиты не тратят на массовый тест без согласования; используют тестовый режим и контролируемый объём.

Мониторинг включает долю ошибок по endpoint, время генерации, размер результата, число повторов, отставание очереди, оставшуюся квоту и возраст задания без результата. Одного сигнала API недоступно недостаточно: проблема может касаться только конкретного шаблона или внешнего ресурса.

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

Docamatic не заменяет визуальный PDF-редактор. Готовый файл нельзя открыть в панели, выбрать абзац мышью и переписать его. Изменения выполняются в исходном HTML, JSON данных или координатах Write to PDF. Для разового ручного исправления удобнее редактор PDF, а для повторяемой автоматизации — API.

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

Base64 ограничен файлами до 4 МБ. Приложение должно обрабатывать возврат URL даже при encode=true. Это особенно важно для отчётов с фотографиями и длинных пакетов после merge. Попытка безусловно декодировать ссылку создаст повреждённый файл или ошибку памяти.

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

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

Автоматическое принятие cookie и click_elements зависят от разметки страницы. После изменения текста кнопки или CSS-класса подготовительный клик перестанет работать либо нажмёт другой элемент. Для критичных документов лучше передавать готовый HTML без интерактивных барьеров.

Модель данных для шаблонов и HTML

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

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

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

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

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

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

Регрессионная проверка PDF и изображений

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

Автоматическая проверка начинается с формата ответа: success, ожидаемого content_type, непустого transaction_id и размера файла выше разумного минимума. Затем PDF открывают библиотекой разбора, считают страницы и извлекают текст. Проверка наличия номера заказа, итоговой суммы и имени получателя обнаруживает пустую страницу и потерянный блок быстрее, чем сравнение только размера. Для image endpoint аналогично проверяют формат PNG, WEBP или JPG и размеры изображения.

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

Для Write to PDF создают отдельный тест на каждый поддерживаемый фон. На контрольной копии размещают маркеры у границ области и проверяют, что текст, картинка, barcode и QR остаются внутри ожидаемых прямоугольников. После замены исходного PDF тест обязательно повторяют. Даже незаметное изменение полей страницы или внутренней рамки может сместить координаты при прежних значениях x и y.

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

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

Построение многошаговых процессов

Сложный пакет документов удобно разбивать на явные шаги. Например, приложение создаёт счёт через Template API, условия через HTML to PDF, затем передаёт оба URL или base64 в Merge API и только после успешного объединения вызывает Encrypt API. У каждого шага сохраняются endpoint, transaction_id, входная ревизия и статус. Такая трассировка показывает, где именно возникла ошибка, и позволяет повторить только незавершённую операцию.

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

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

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

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

Для последовательности template, merge и encrypt полезно определить единый корреляционный идентификатор приложения. Docamatic возвращает собственный transaction_id для каждой операции, а корреляционный идентификатор объединяет их в один заказ. В панели Logs ищут отдельный запрос, в журнале приложения — весь маршрут. Это особенно важно, когда несколько пакетов создаются одновременно и имена файлов похожи.

Перенос ручного документооборота в Docamatic

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

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

Для макета выбирают подходящий механизм. Стандартный invoice или packing slip можно проверить через Template API. Фирменный отчёт с таблицами и особой типографикой переводят в HTML и print CSS. Утверждённый государственный или партнёрский бланк оставляют PDF-фоном и заполняют через write. Выбор делается по структуре документа, а не по желанию использовать один endpoint для всех случаев.

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

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

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

Локализация, печать и доступность результата

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

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

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

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

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

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

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

Программа	Лучше подходит для	Главное ограничение
Docamatic	HTML в PDF, готовых JSON-шаблонов, записи поверх PDF, слияния и шифрования в одном API	Нет свободного визуального конструктора собственных шаблонов
DocRaptor	Сложной печатной вёрстки HTML/CSS, CSS Paged Media, многостраничных отчётов и PDF с продвинутой типографикой	Не ориентирован на каталог простых готовых бизнес-шаблонов
PDFShift	Конвертации HTML или страниц в PDF и растровые форматы с настройками рендеринга и шаблонным endpoint	Не заменяет координатное заполнение произвольного существующего PDF
PDFMonkey	Командной работы с шаблонами, визуального Builder и кодовых HTML/CSS/Liquid-шаблонов	Рабочий процесс сильнее привязан к созданию и публикации шаблона
APITemplate.io	Визуальных и HTML-шаблонов, генерации PDF и изображений, интеграций и управления шаблонами	Для простого заполнения готового PDF потребуется отдельный сценарий

Docamatic стоит выбирать, когда в одном процессе нужны не только HTML в PDF, но и готовые бизнес-макеты, скриншоты, запись текста и кодов поверх PDF, merge и парольная защита. DocRaptor сильнее в сложной печатной типографике и CSS Paged Media. PDFShift удобен для прямой конвертации HTML и страниц. PDFMonkey и APITemplate.io лучше подходят командам, которым нужен визуальный конструктор собственных шаблонов и управление ими через панель.

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

Как выбрать подходящий способ генерации в Docamatic

Готовый Template API выбирают, когда структура совпадает с доступным счётом, packing slip, возвратом, коммерческим инвойсом, предложением, этикеткой или бейджем. Это самый короткий путь: приложение формирует JSON, а макет уже подготовлен. До запуска проверяют длину полей и локализацию подписей.

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

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

Image API используют для превью, карточек, снимков страниц и растровых этикеток. Merge собирает пакет из готовых частей, encrypt добавляет пароль на финальном этапе. Эти операции лучше строить как последовательность с сохранением transaction_id каждого шага, чтобы при ошибке не повторять всю цепочку.

Контрольный список перед выпуском документов

1. Проверить исходные данные, арифметику сумм, формат дат и валют до обращения к API.
2. Выбрать один источник размера страницы: параметры запроса или CSS @page.
3. Использовать test=true до визуальной и автоматической проверки макета.
4. Протестировать минимальный, средний и максимальный объём данных.
5. Проверить кириллицу, валютные символы, длинные имена и адреса.
6. Сохранить transaction_id, безопасное имя, размер и ревизию шаблона.
7. Обработать коды 400, 401, 403, 405, 408, 415, 422, 429 и 500 разными стратегиями.
8. Не считать encode гарантией base64 для результата больше 4 МБ.
9. Перенести готовый файл в постоянное хранилище и проверить его до удаления временной копии.
10. Ограничить частоту, повторы и общее число генераций на одну бизнес-операцию.
11. Проверить webhook на повторную доставку и сделать обработчик идемпотентным.
12. Напечатать этикетки и отсканировать штрихкоды на реальном оборудовании.
13. Перед шифрованием завершить проверку содержимого и выбрать совместимый AES-режим.
14. Передавать пароль отдельным каналом и никогда не записывать его в журнал.
15. Зафиксировать версию данных и шаблона, чтобы повторная выдача была воспроизводимой.

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

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