API PDF z szablonu dla stabilnych kontraktów dokumentów
Renderuj PDF ze stabilnego template_id i tablicy data, gdy powtarzalny layout ma być zarządzany raz i używany ponownie przez ERP, OMS, WMS albo wywołujących SaaS.
/api/v1/template-render Renderować powtarzalne PDF przez wysłanie stabilnego template_id i tablicy danych biznesowych, zamiast wymagać od każdego wywołującego opisywania stron, współrzędnych i elementów layoutu w każdym żądaniu.
Kiedy użyć tej API
- Layout dokumentu jest zatwierdzony i używany ponownie przez wielu wywołujących albo wiele zadań.
- Wywołujący powinni wysyłać dane biznesowe, a nie JSON layoutu na poziomie współrzędnych.
- Potrzebujesz wyjścia dla faktury, listy pakowej, etykiety wysyłkowej albo własnego szablonu.
- Chcesz kontrolować aktywne rewizje szablonu poza kodem wywołującego.
Czego nie zastępuje
- Nadal projektujesz layout. Używaj JSON Render, dopóki współrzędne i pola nie są stabilne.
- Potrzebujesz dowolnej konwersji HTML-to-PDF.
- Potrzebujesz pakietowania e-faktur PDF/A-3b z osadzonym CII XML.
Który endpoint wywołać
/api/v1/template-render
Template Render to domyślna ścieżka dla tego procesu.
/api/v1/pdf/render
Użyj, gdy proces wymaga powiązanej ścieżki API, kontraktu szablonu albo sprawdzenia capabilities.
Minimalny request
POST /api/v1/template-render - render jednej faktury z szablonu.
{
"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"
}
]
}
]
}
Co obsługuje gPdf
- Wyszukiwanie szablonu przez stabilny template_id.
- Renderowanie każdego elementu data względem aktywnego szablonu.
- Łączenie wyrenderowanych stron w pojedynczy PDF w granicach publicznych limitów endpointu.
- Wspólne uwierzytelnianie, identyfikator żądania i zachowanie koperty błędu.
Co kontroluje Twój system
- Wybór szablonu, mapowanie pól, dane biznesowe i autoryzację wywołującego.
- Proces publikowania szablonu, komunikację zmian i pokrycie testami.
- Porcjowanie, kolejkowanie i retry przy renderowaniu wielu dokumentów.
Checklist produkcyjny
- Traktuj template_id jako nieprzezroczysty stabilny kontrakt.
- Waliduj pola data przed wywołaniem Template Render.
- Utrzymuj testy golden-PDF dla aktywnego szablonu i reprezentatywnych danych.
- Dziel duże partie zgodnie z publicznymi limitami Template Render.
- Loguj template_id, ID żądania i ID obiektów biznesowych dla śledzenia.
Granice deklaracji
- Template Render sam w sobie nie jest narzędziem projektowym; szablony muszą być już opublikowane.
- gPdf nie wyprowadza brakujących danych biznesowych z szablonu.
- Template Render nie zastępuje endpointu E-Invoice Render.
Template Render jest produkcyjną warstwą kontraktu
JSON Render sprawdza się najlepiej podczas projektowania layoutu. Template
Render to warstwa używana po tym, jak layout staje się kontraktem. Wywołujący
wysyłają template_id oraz data; aktywny szablon odpowiada za strukturę
dokumentu.
Dzięki temu kod wywołujących pozostaje mniejszy, a zmiany szablonów łatwiej przeglądać, testować i wdrażać.
FAQ
- Kiedy używać Template Render zamiast JSON Render?
- Używaj Template Render po zatwierdzeniu layoutu, gdy wywołujący powinni wysyłać wyłącznie dane biznesowe.
- Czy template_id jest stabilny?
- Tak. Dokumentacja Template API opisuje template_id jako stabilny identyfikator widoczny dla wywołującego.
- Czy jedno żądanie może renderować wiele elementów data?
- Tak, Template Render przyjmuje tablicę data w granicach publicznych limitów endpointu.
- Czy Template Render może tworzyć e-faktury?
- Nie. Pakietowanie Factur-X i ZUGFeRD PDF/A-3b używa endpointu E-Invoice Render.