API JSON у PDF для структурованого створення документів
Перетворюйте структуровані JSON DocumentRequest на PDF зі сторінками, координатами, текстом, таблицями, штрихкодами, метаданими та налаштуваннями PDF/A.
/api/v1/pdf/render Перетворити структуровані прикладні дані на детерміновані PDF-документи без запуску браузера, HTML/CSS або зберігання файлів клієнтів. Ваша система надсилає сторінки, елементи, координати, налаштування й бізнес-вміст; gPdf повертає відповідь application/pdf.
Коли використовувати цю API
- У вашому бекенді вже є структуровані дані й потрібна PDF-відповідь.
- Потрібні явні сторінки, координати, елементи, штрихкоди й налаштування замість HTML-макета.
- Потрібен повторюваний вивід для рахунків, етикеток, звітів, виписок або згенерованих пакетів.
- Потрібно перевірити тіло запиту в Playground, перш ніж переносити token у бойове середовище.
Що вона не замінює
- Потрібне довільне перетворення HTML у PDF. gPdf використовує JSON DocumentRequest, а не браузерний DOM.
- Команді потрібен стабільний контракт template_id. Після публікації макета використовуйте Template Render.
- Потрібне пакування електронного рахунку Factur-X або ZUGFeRD. Використовуйте маршрут E-Invoice Render.
Який шлях API викликати
/api/v1/pdf/render
JSON Render — типовий шлях для цього сценарію.
/api/v1/template-render
Використовуйте, коли сценарію потрібен пов’язаний API-шлях, контракт шаблону або перевірка можливостей.
Мінімальний запит
POST /api/v1/pdf/render - односторінковий JSON DocumentRequest.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Hello from gPdf",
"style": {
"font_size": 18,
"font_family": "NotoSans-Regular"
}
}
]
}
]
}
Що виконує gPdf
- Рендеринг DocumentRequest зі сторінок і елементів.
- Текст, таблиці, зображення, векторні штрихкоди, лінії, фігури, водяні знаки, метадані та налаштування PDF/A.
- Вбудовування шрифтів і резервний підбір для латиниці, CJK, emoji-сумісних та інших підтримуваних писемностей.
- Бінарна PDF-відповідь і спільний конверт кодів помилок gPdf у разі збою.
Що контролює ваша система
- Бізнес-дані, мапінг полів і семантику документа.
- Request ID, стратегію retry та ідемпотентності, імена файлів і зберігання після відповіді.
- Будь-які податкові, інвойсингові, перевізницькі правила відповідності або клієнтські правила до рендерингу.
Чеклист для робочого запуску
- Генеруйте й передавайте X-Request-Id для трасування.
- Перевіряйте тіло запиту за OpenAPI або документацією перед live-трафіком.
- Зробіть базовий URL API конфігурованим і зберігайте bearer token поза вихідним кодом.
- Вирішіть, чи має результат повертатися inline або в режимі attachment.
- Додайте golden-PDF тести для критичних макетів, щоб зміни шаблону або даних були помітні.
Межі заявлених можливостей
- Це не HTML у PDF і тут не запускається Chromium.
- API рендерить описаний вами документ; він не виводить юридичний або бізнес-зміст із ваших даних.
- Для повторюваних макетів Template Render зазвичай кращий публічний контракт.
Як працює процес JSON Render
JSON Render — найнижчий публічний шлях рендерингу. Ваш застосунок надсилає структуру документа напряму: розмір сторінки, елементи, координати, стилі, метадані, режим виводу й необов’язкові налаштування PDF/A. Це правильний рівень, коли макет документа генерується кодом або команда хоче контролювати PDF на рівні пікселів.
Контракт API явний. Якщо ваша система надсилає текстовий елемент, gPdf рендерить текстовий елемент. Якщо вона надсилає елемент штрихкоду, gPdf малює штрихкод як векторний PDF-вміст. gPdf не читає бізнес-наміри з тіла запиту і не вирішує, чи правильний номер рахунку, tracking-значення перевізника або податкове поле.
Коли переходити на Template Render
Якщо той самий макет повторно використовується в кількох системах, опублікуйте
його як шаблон і викликайте POST /api/v1/template-render з template_id плюс
data[]. Так відповідальність за макет виходить із кожного сервісу-викликача і ваш ERP,
OMS, WMS або SaaS-бекенд отримує стабільний контракт полів.
Використовуйте JSON Render для створення макета, одноразових документів і програмно згенерованих документів. Використовуйте Template Render, коли макет зафіксований, а в кожному запиті змінюються лише бізнес-дані.
Production-форма
У бойовому середовищі ставтеся до PDF-запиту як до будь-якого важливого API-виклику: додавайте request ID, задавайте timeout, робіть повторні спроби ідемпотентними, логуйте метадані відповіді та зберігайте повернений PDF лише у власній системі, якщо потрібне утримання. Шлях рендерингу gPdf після стандартної відповіді не зберігає стан.
FAQ
- Це API HTML у PDF?
- Ні. gPdf приймає структурований JSON DocumentRequest зі сторінками, елементами, координатами й налаштуваннями. Він не запускає браузер і не виконує довільний HTML/CSS.
- Який маршрут API викликати спочатку?
- Почніть із POST /api/v1/pdf/render, коли потрібен прямий контроль над макетом. Перейдіть на POST /api/v1/template-render, коли макет має стати стабільним контрактом template_id.
- API повертає PDF напряму?
- Так. Успішний рендер повертає application/pdf. Помилки використовують спільний JSON-конверт помилки з кодом API-XXX і req_id.
- Чи можна протестувати без інтеграції?
- Використовуйте gPdf Playground, щоб інтерактивно перевірити JSON-тіло запиту, а потім перенесіть ту саму форму DocumentRequest у бекенд-клієнт.