Template PDF API для стабильных document contracts
Рендерьте PDF из стабильного template_id и data array, когда повторяемые layouts должны быть описаны один раз и использоваться ERP, OMS, WMS или SaaS callers.
/api/v1/template-render Рендерить повторяемые PDF, отправляя стабильный `template_id` и business data array вместо того, чтобы каждый caller описывал pages, coordinates и layout elements в каждом request.
Когда использовать эту API
- Document layout утвержден и используется несколькими callers или jobs.
- Callers должны отправлять business data, а не coordinate-level layout JSON.
- Нужен invoice, packing list, shipping label или custom template output.
- Active template revisions должны контролироваться вне caller.
Что она не заменяет
- Layout еще проектируется. Используйте JSON Render, пока coordinates и fields не станут стабильными.
- Нужна arbitrary HTML-to-PDF conversion.
- Нужен e-invoice PDF/A-3b packaging со встроенным CII XML.
Какой endpoint вызывать
/api/v1/template-render
Template Render — путь по умолчанию для этого сценария.
/api/v1/pdf/render
Используйте, когда сценарию нужен связанный API-путь, контракт шаблона или проверка возможностей.
Минимальный запрос
POST /api/v1/template-render - отрендерить один invoice из template.
{
"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
- Template lookup по стабильному `template_id`.
- Rendering каждого data item against the active template.
- Concatenating rendered pages в один PDF в пределах public endpoint limits.
- Общее authentication, request ID и error envelope behavior.
Что контролирует ваша система
- Template selection, field mapping, business data и caller authorization.
- Template publication workflow, change communication и test coverage.
- Chunking, queueing и retries при рендеринге многих документов.
Production-чеклист
- Относитесь к `template_id` как к opaque stable contract.
- Валидируйте data fields перед вызовом Template Render.
- Держите golden-PDF tests для active template и representative data.
- Дробите large batches согласно public Template Render limits.
- Логируйте `template_id`, request ID и business object IDs для traceability.
Границы заявлений
- Template Render сам по себе не является design tool; templates уже должны быть published.
- gPdf не выводит missing business data из template.
- Template Render не заменяет E-Invoice Render endpoint.
Template Render — production contract layer
JSON Render идеален, пока layout проектируется. Template Render — слой для
момента, когда layout стал contract. Callers отправляют template_id и data; за
структуру документа отвечает active template.
Это уменьшает callers и упрощает review, testing и rollout изменений template.
FAQ
- Когда использовать Template Render вместо JSON Render?
- Используйте Template Render после утверждения layout, когда callers должны отправлять только business data.
- Стабилен ли template_id?
- Да. Template API docs описывают template_id как стабильный caller-facing identifier.
- Может ли один request рендерить несколько data items?
- Да, Template Render принимает data array в пределах public endpoint limits.
- Может ли Template Render создавать e-invoices?
- Нет. Factur-X и ZUGFeRD PDF/A-3b packaging используют E-Invoice Render endpoint.