PDF по шаблону: API для production-систем
Генерация PDF по шаблону из структурированных backend-данных без браузера: gPdf отвечает за PDF-рендеринг, бизнес-правила остаются в вашей системе.
/api/v1/template-render Генерация PDF по шаблону как воспроизводимого PDF из структурированных данных. gPdf создает документ; ваша система отвечает за смысл данных и состояние процесса.
Когда использовать эту API
- Backend уже содержит данные для PDF по шаблону и нужен стабильный PDF-ответ.
- Нужно избежать Chromium или HTML-to-PDF в операционном документе.
- Нужен повторяемый результат для перепечатки, аудита или пакетной обработки.
Что она не заменяет
- gPdf не покупает доставку, не подает налоги, не создает внешние заказы и не является фискальной системой.
- gPdf не заменяет бизнес-логику, проверку данных и интеграции с marketplace.
Какой endpoint вызывать
/api/v1/template-render
Template Render — путь по умолчанию для этого сценария.
/api/v1/pdf/render
Используйте, когда сценарию нужен связанный API-путь, контракт шаблона или проверка возможностей.
Минимальный request
/api/v1/template-render - PDF по шаблону
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-001",
"date_of_issue": "2026-05-29",
"date_due": "2026-06-28",
"issuer_name": "Acme Cloud Inc.",
"issuer_address": "88 Harbor Rd, Long Beach, CA",
"bill_to_name": "Receiver Inc.",
"bill_to_address": "123 Main St, Los Angeles, CA",
"subtotal": "$100.00",
"total": "$100.00",
"amount_due": "$100.00",
"items": [
{
"description": "Service A",
"qty": 1,
"unit_price": "$100.00",
"amount": "$100.00"
}
]
}
]
}
Что выполняет gPdf
- PDF-рендеринг для PDF по шаблону из структурированного request.
- Текст, таблицы, линии, штрихкоды, страницы, метаданные и параметры вывода согласно request.
- Детерминированный вывод для retries, перепечатки и аудита.
Что контролирует ваша система
- Корректные данные для PDF по шаблону, бизнес-правила и состояние операции.
- Аутентификация, хранение, внешние workflow и приемочные проверки.
Production checklist
- Проверьте на реальных данных и в системах, которые будут принимать PDF.
- Сохраняйте request ID и доказательства проверки для поддержки, аудита и перепечатки.
- Переведите утвержденный layout в template, если им пользуются несколько систем.
Границы заявлений
- gPdf рендерит PDF из request; он не заменяет workflow продукта, базу данных или бизнес-валидацию.
- Ваша система отвечает за семантику данных, retries, хранение и финальную приемку.
Форма API
API: PDF по шаблону — production workflow на публичных API gPdf. Request описывает данные, layout, settings и PDF-части для рендеринга. gPdf создает PDF, а ваша система сохраняет смысл бизнес-события.
Выбор endpoint
Для этого сценария endpoint по умолчанию — /api/v1/template-render. Template Render используйте после утверждения layout. E-Invoice Render используйте только для Factur-X / ZUGFeRD PDF/A-3b с встроенным EN 16931 CII XML.
Проверка перед production
Проверяйте PDF по шаблону на реальных данных и в downstream-системах. Храните request ID, PDF и результаты проверок для поддержки, аудита и перепечатки.
FAQ
- Это отдельный endpoint?
- API: PDF по шаблону сопоставляет сценарий с публичной API gPdf. Страница объясняет, какой путь вызвать и что должен содержать request.
- Можно использовать templates?
- Да. JSON Render подходит, пока layout меняется; Template Render — когда layout утвержден и callers отправляют только бизнес-данные.
- Что проверить перед production?
- Проверяйте реальные данные и downstream-системы: принтеры, сканеры, валидаторы, бухгалтерию или marketplace.