API PDF-шаблонів для стабільних контрактів документів
Рендерте PDF зі стабільного template_id і масиву data, коли повторюваний макет має належати одному місцю й повторно використовуватися ERP, OMS, WMS або SaaS-сервісами.
/api/v1/template-render Рендерити повторювані PDF, надсилаючи стабільний template_id і масив бізнес-даних замість того, щоб кожен сервіс-викликач описував сторінки, координати й елементи макета в кожному запиті.
Коли використовувати цю API
- Макет документа затверджено й він повторно використовується кількома сервісами-викликачами або задачами.
- Caller мають надсилати бізнес-дані, а не JSON макета на рівні координат.
- Потрібен вивід для рахунку, пакувального листа, транспортної етикетки або власного шаблону.
- Потрібно керувати активними ревізіями шаблону поза сервісом-викликачем.
Що вона не замінює
- Макет ще проєктується. Використовуйте JSON Render, доки координати й поля не стабільні.
- Потрібне довільне перетворення HTML у PDF.
- Потрібне пакування PDF/A-3b електронного рахунку з вбудованим CII XML.
Який шлях API викликати
/api/v1/template-render
Template Render — типовий шлях для цього сценарію.
/api/v1/pdf/render
Використовуйте, коли сценарію потрібен пов’язаний API-шлях, контракт шаблону або перевірка можливостей.
Мінімальний запит
POST /api/v1/template-render - рендер одного рахунку з шаблону.
{
"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_id.
- Рендеринг кожного елемента data за активним шаблоном.
- Об’єднання відрендерених сторінок в один PDF у межах лімітів публічного маршруту API.
- Спільну автентифікацію, request ID і поведінку конверта помилок.
Що контролює ваша система
- Вибір шаблону, мапінг полів, бізнес-дані й авторизацію сервісів-викликачів.
- Процес публікації шаблонів, комунікацію змін і тестове покриття.
- Розбиття на частини, постановку в чергу та retry під час рендерингу багатьох документів.
Чеклист для робочого запуску
- Сприймайте template_id як непрозорий стабільний контракт.
- Валідуйте поля data перед викликом Template Render.
- Підтримуйте golden-PDF тести для активного шаблону й репрезентативних даних.
- Діліть великі пакети відповідно до публічних лімітів Template Render.
- Логуйте template_id, request ID і ID бізнес-об’єктів для трасування.
Межі заявлених можливостей
- Template Render сам по собі не є дизайн-інструментом; шаблони мають бути вже опубліковані.
- gPdf не виводить відсутні бізнес-дані з шаблону.
- Template Render не замінює маршрут E-Invoice Render.
Template Render — бойовий шар контракту
JSON Render ідеально підходить, доки макет проєктується. Template Render — це
шар, який варто використовувати після того, як макет стає контрактом. Сервіси-викликачі
надсилають template_id і data; активний шаблон відповідає за структуру
документа.
Це зменшує код сервісів-викликачів і полегшує перегляд, тестування та викатку змін шаблону.
FAQ
- Коли використовувати Template Render замість JSON Render?
- Використовуйте Template Render після затвердження макета, коли сервіси-викликачі мають надсилати лише бізнес-дані.
- Чи стабільний template_id?
- Так. Документація Template API описує template_id як стабільний ідентифікатор, видимий сервісу-викликачу.
- Чи може один запит рендерити кілька елементів data?
- Так, Template Render приймає масив data у межах публічних лімітів маршруту API.
- Чи може Template Render створювати електронні рахунки?
- Ні. Пакування Factur-X і ZUGFeRD PDF/A-3b використовує маршрут E-Invoice Render.