API faktur PDF dla systemów billingowych i finansowych
Generuj zwykłe faktury PDF z danych billingowych przez JSON Render albo Template Render, pozostawiając logikę podatków i księgowości w swoim systemie.
/api/v1/pdf/render Zamieniaj dane faktury z systemu billingowego, ERP albo aplikacji SaaS w czytelną fakturę PDF, pozostawiając numerację, podatki, status płatności i znaczenie księgowe w systemie wywołującym.
Kiedy użyć tej API
- Potrzebujesz zwykłych faktur PDF dla klientów, potwierdzeń, zestawień albo eksportów księgowych.
- Twój system odpowiada już za numery faktur, obliczenia podatków, pozycje i status płatności.
- Chcesz tabel, sum, metadanych i opcjonalnych ustawień PDF/A bez uruchamiania przeglądarki.
- Chcesz kontraktu template_id dla powtarzalnych układów faktur.
Czego nie zastępuje
- Potrzebujesz prawnego pakietu e-faktury, takiego jak Factur-X albo ZUGFeRD. Użyj E-Invoice Render.
- Oczekujesz, że gPdf obliczy podatki, zweryfikuje reguły księgowe albo uzgodni płatności.
- Chcesz dowolnej konwersji faktur HTML zamiast strukturalnego JSON albo szablonów.
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.
/api/v1/e-invoice/render
Użyj, gdy proces wymaga powiązanej ścieżki API, kontraktu szablonu albo sprawdzenia capabilities.
Minimalny request
POST /api/v1/pdf/render - minimalny nagłówek faktury i suma.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 18, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 20,
"y": 42,
"content": "Bill to: Example Customer\nAmount due: USD 245.00",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "line",
"x1": 20,
"y1": 62,
"x2": 190,
"y2": 62
}
]
}
]
}
Co obsługuje gPdf
- Renderowanie faktur PDF ze stron JSON albo danych szablonu.
- Tekst, tabele, bloki sum, paginację, metadane i opcjonalne wyjście PDF/A.
- Template Render dla stabilnych układów faktur używanych przez wiele systemów.
- Binarną odpowiedź PDF i spójną kopertę błędu API.
Co kontroluje Twój system
- Numery faktur, status płatności, obliczenia podatków, rabaty, korekty i znaczenie w księdze.
- Dane klienta i wystawcy, mapowanie pozycji, waluty oraz reguły zaokrągleń.
- Retencję, dostarczanie, email, linki płatnicze i uzgodnienia z systemem księgowym.
Checklist produkcyjny
- Potwierdź, że każde widoczne pole faktury mapuje się na źródłowe dane billingowe.
- Przetestuj przepełnienie pozycji, długie nazwy klientów, faktury wielostronicowe i sumy.
- Zdecyduj, czy układ należy do JSON Render, czy do opublikowanego szablonu.
- Oddziel zwykłe generowanie faktur PDF od prawnego pakowania e-faktur.
- Przechowuj request ID i nazwy plików wynikowych razem z rekordami faktur.
Granice deklaracji
- Zwykłe faktury PDF nie są tym samym co prawne obowiązki dotyczące e-faktur.
- gPdf renderuje dokument faktury; nie oblicza podatków ani stanu księgowego.
- Wyjście Factur-X / ZUGFeRD należy do POST /api/v1/e-invoice/render.
Zwykłe faktury a e-faktury
Zwykła faktura PDF to dokument, który czyta klient. Można ją wygenerować przez JSON Render albo Template Render. Twój system decyduje o numerze faktury, podatkach, pozycjach, walucie i statusie płatności, a gPdf renderuje widoczny PDF.
Prawna e-faktura to inny przypadek. Factur-X i ZUGFeRD łączą czytelną fakturę
PDF/A-3b z osadzonym XML CII EN 16931. Dla takiego pakietu użyj
POST /api/v1/e-invoice/render.
Template Render zwykle jest endpointem produkcyjnym
Zespoły finansowe rzadko chcą, aby każda usługa odtwarzała współrzędne faktury.
Typowa ścieżka to zaprojektować fakturę raz, opublikować ją jako szablon i
przekazać systemom wywołującym stabilny template_id oraz schemat danych. JSON
Render pozostaje przydatny dla niestandardowych układów, narzędzi wewnętrznych
i prototypowania szablonów.
Trzymaj logikę księgową wcześniej w systemie
gPdf powinien otrzymywać finalne wartości do wyświetlenia, a nie nierozstrzygnięte decyzje księgowe. Oblicz podatki, rabaty, zaokrąglenia, status płatności i kwalifikację faktury przed wywołaniem Render API. Dzięki temu wynik PDF jest deterministyczny, a system finansowy pozostaje źródłem prawdy.
FAQ
- Czy faktura PDF jest tym samym co e-faktura?
- Nie. Zwykła faktura PDF jest czytelnym dla człowieka wyjściem. E-faktura Factur-X albo ZUGFeRD dodatkowo osadza XML CII EN 16931 wewnątrz opakowania PDF/A-3b.
- Którego endpointu używać dla powtarzalnych faktur?
- Użyj Template Render, gdy układ faktury jest stabilny, a systemy wywołujące powinny wysyłać tylko template_id i data. Użyj JSON Render, gdy kod odpowiada za układ.
- Czy gPdf oblicza podatki?
- Nie. System billingowy albo księgowy oblicza podatki, sumy, rabaty i status płatności przed wysłaniem danych do renderowania.
- Czy faktury PDF mogą używać PDF/A?
- Tak, JSON Render obsługuje ustawienia PDF/A. Użyj E-Invoice Render konkretnie wtedy, gdy faktura musi zostać spakowana jako Factur-X albo ZUGFeRD.