API JSON do PDF do strukturalnego generowania dokumentów
Zamieniaj strukturalne payloady JSON DocumentRequest na PDF ze stronami, współrzędnymi, tekstem, tabelami, kodami kreskowymi, metadanymi i ustawieniami PDF/A.
/api/v1/pdf/render Przekształcać strukturalne dane aplikacji w deterministyczne dokumenty PDF bez uruchamiania przeglądarki, wysyłania HTML/CSS ani przechowywania plików klientów. Twój system wysyła strony, elementy, współrzędne, ustawienia i treść biznesową; gPdf zwraca odpowiedź application/pdf.
Kiedy użyć tej API
- Backend ma już dane strukturalne i potrzebuje odpowiedzi PDF.
- Wolisz jawne strony, współrzędne, elementy, kody kreskowe i ustawienia zamiast layoutu HTML.
- Potrzebujesz powtarzalnego wyniku dla faktur, etykiet, raportów, zestawień albo generowanych pakietów dokumentów.
- Chcesz przetestować payloady w Playground, zanim użyjesz tokena w produkcji.
Czego nie zastępuje
- Potrzebujesz dowolnej konwersji HTML-to-PDF. gPdf używa JSON DocumentRequest, a nie DOM przeglądarki.
- Zespół potrzebuje stabilnego kontraktu template_id. Po opublikowaniu layoutu użyj Template Render.
- Potrzebujesz pakietowania e-faktur Factur-X albo ZUGFeRD. Użyj endpointu E-Invoice Render.
Który endpoint wywołać
/api/v1/pdf/render
JSON Render to domyślna ścieżka dla tego procesu.
/api/v1/template-render
Użyj, gdy proces wymaga powiązanej ścieżki API, kontraktu szablonu albo sprawdzenia capabilities.
Minimalny request
POST /api/v1/pdf/render - jednostronicowy JSON DocumentRequest.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Hello from gPdf",
"style": {
"font_size": 18,
"font_family": "NotoSans-Regular"
}
}
]
}
]
}
Co obsługuje gPdf
- Renderowanie DocumentRequest ze stron i elementów.
- Tekst, tabele, obrazy, wektorowe kody kreskowe, linie, kształty, znaki wodne, metadane i ustawienia PDF/A.
- Osadzanie fontów i fallback dla łacinki, CJK, skryptów obsługujących emoji oraz innych wspieranych pism.
- Binarną odpowiedź PDF oraz wspólną kopertę błędu gPdf w razie niepowodzenia.
Co kontroluje Twój system
- Dane biznesowe, mapowanie pól i semantykę dokumentu.
- Identyfikatory żądań, strategię retry i idempotencji, nazwy plików oraz przechowywanie po otrzymaniu odpowiedzi.
- Wszelkie reguły podatkowe, fakturowe, przewoźnika, zgodności albo specyficzne dla klienta przed renderowaniem.
Checklist produkcyjny
- Generuj i przekazuj X-Request-Id dla śledzenia żądań.
- Waliduj payloady względem OpenAPI albo dokumentacji przed wysłaniem ruchu produkcyjnego.
- Trzymaj bazowy URL API jako konfigurację i przechowuj bearer token poza kodem źródłowym.
- Zdecyduj, czy wynik ma być zwracany jako inline czy attachment.
- Dodaj testy golden-PDF dla krytycznych layoutów, aby zmiany szablonu lub danych były widoczne.
Granice deklaracji
- To nie jest HTML-to-PDF i nie uruchamia Chromium.
- API renderuje opisany przez Ciebie dokument; nie wyprowadza znaczenia prawnego ani biznesowego z danych.
- Dla powtarzalnych layoutów Template Render zwykle jest lepszym publicznym kontraktem.
Jak działa proces JSON Render
JSON Render to najniższy publiczny poziom renderowania. Aplikacja wysyła strukturę dokumentu bezpośrednio: rozmiar strony, elementy, współrzędne, stylowanie, metadane, tryb wyjścia oraz opcjonalne ustawienia PDF/A. To właściwa warstwa, gdy layout dokumentu powstaje w kodzie albo gdy zespół potrzebuje kontroli PDF na poziomie pikseli.
Kontrakt API jest jawny. Jeśli system wyśle element tekstowy, gPdf wyrenderuje element tekstowy. Jeśli wyśle element kodu kreskowego, gPdf narysuje kod kreskowy jako wektorową treść PDF. gPdf nie odczytuje intencji biznesowej z payloadu i nie decyduje, czy numer faktury, wartość śledzenia przewoźnika albo pole podatkowe jest poprawne.
Kiedy przejść na Template Render
Jeśli ten sam layout jest wielokrotnie używany w różnych systemach, opublikuj
go jako szablon i wywołuj POST /api/v1/template-render z template_id oraz
data[]. To przenosi odpowiedzialność za layout poza każdego wywołującego i
daje ERP, OMS, WMS albo backendowi SaaS stabilny kontrakt pól.
Używaj JSON Render do tworzenia layoutów, dokumentów jednorazowych i dokumentów generowanych programowo. Używaj Template Render, gdy layout jest stały, a w każdym żądaniu zmieniają się wyłącznie dane biznesowe.
Kształt produkcyjny
W produkcji traktuj żądanie PDF jak każde istotne wywołanie API: dodaj identyfikator żądania, ustaw timeout, zadbaj o idempotentne retry, loguj metadane odpowiedzi i przechowuj zwrócony PDF wyłącznie we własnym systemie, jeśli wymaga tego retencja. Standardowa ścieżka renderowania gPdf jest bezstanowa po zwróceniu odpowiedzi.
FAQ
- Czy to jest API HTML-to-PDF?
- Nie. gPdf przyjmuje strukturalny JSON DocumentRequest ze stronami, elementami, współrzędnymi i ustawieniami. Nie uruchamia przeglądarki ani dowolnego HTML/CSS.
- Który endpoint wywołać jako pierwszy?
- Zacznij od POST /api/v1/pdf/render, gdy chcesz bezpośrednio kontrolować layout. Przejdź na POST /api/v1/template-render, gdy layout ma stać się stabilnym kontraktem template_id.
- Czy API zwraca PDF bezpośrednio?
- Tak. Udane renderowanie zwraca application/pdf. Błędy używają wspólnej koperty JSON z kodem API-XXX i req_id.
- Czy mogę testować bez budowania integracji?
- Użyj gPdf Playground do interaktywnego testowania payloadów JSON, a potem przenieś ten sam kształt DocumentRequest do klienta backendowego.