API PDF potwierdzeń płatności dla ecommerce i płatności SaaS
Generuj PDF potwierdzeń płatności z danych zamówień, płatności, podatków i zwrotów, z kodami QR, kodami kreskowymi, ustawieniami PDF/A i powtarzalnym wyjściem szablonowym.
/api/v1/pdf/render Zamieniaj zakończone dane zamówienia, płatności, zwrotu i podatków w PDF potwierdzenia płatności, który można wysłać emailem, przechować, wydrukować albo dołączyć do konta klienta bez wymagania, aby każdy system wywołujący sam rysował PDF.
Kiedy użyć tej API
- Twój system odpowiada już za status płatności, numer potwierdzenia, linie podatkowe i dane klienta.
- Potrzebujesz PDF potwierdzenia płatności do emaila, historii konta, obsługi klienta albo eksportu audytowego.
- Chcesz umieścić w potwierdzeniu kody QR albo kody kreskowe dla wyszukiwania, zwrotu albo odbioru.
- Potrzebujesz stabilnego szablonu potwierdzenia po zatwierdzeniu układu.
Czego nie zastępuje
- Potrzebujesz przetwarzania płatności albo wykonania zwrotu. gPdf renderuje potwierdzenie; system płatniczy odpowiada za przepływ środków.
- Potrzebujesz prawnego pakowania e-faktury. Dla wyjścia Factur-X albo ZUGFeRD użyj endpointu E-Invoice Render.
- Potrzebujesz sterowania sprzętem POS albo logiki szuflady kasowej.
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 - kompaktowe potwierdzenie z kodem QR do wyszukiwania.
{
"pages": [
{
"size": "a6",
"elements": [
{
"type": "text",
"x": 10,
"y": 12,
"content": "Receipt R-2026-1001",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 10,
"y": 28,
"content": "Order total: $82.40\nPaid by card ending 4242\nTax: $6.10",
"style": { "font_size": 10, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "qrcode",
"content": "https://example.com/receipts/R-2026-1001",
"x": 10,
"y": 58,
"width": 28,
"height": 28
}
]
}
]
}
Co obsługuje gPdf
- Renderowanie stron potwierdzenia z danych JSON Render.
- Tekst, sumy, pozycje, kody QR, kody kreskowe, metadane i opcjonalne ustawienia PDF/A.
- Wiązanie Template Render, gdy ten sam układ potwierdzenia jest używany wielokrotnie.
- Binarne wyjście PDF ze wspólną kopertą błędu gPdf w przypadku niepowodzenia.
Co kontroluje Twój system
- Autoryzację płatności, capture, zwrot, obliczenia podatków i numerację potwierdzeń.
- Tożsamość klienta, stan zamówienia, formatowanie waluty i politykę retencji.
- Dostarczenie emailem, przechowywanie na koncie i obsługę duplikatów potwierdzeń.
Checklist produkcyjny
- Używaj stabilnego numeru potwierdzenia i przekazuj X-Request-Id przy każdym renderowaniu.
- Zdecyduj, czy potwierdzenia mają być regenerowane z danych źródłowych, czy przechowywane po pierwszym renderowaniu.
- Przetestuj długie nazwy pozycji, zwroty, rabaty, wiele linii podatkowych i zamówienia zerowe.
- Przejdź na Template Render, gdy zespoły obsługi i finansów zatwierdzą układ.
- Trzymaj decyzje płatnicze i podatkowe poza żądaniem renderowania.
Granice deklaracji
- gPdf nie przetwarza płatności, nie oblicza podatków i nie wykonuje zwrotów.
- PDF potwierdzenia płatności nie jest automatycznie prawną e-fakturą.
- Twój system odpowiada za prawdę biznesową; gPdf renderuje jej reprezentację PDF.
PDF potwierdzenia płatności to wyjście renderowania
To nie jest osobny endpoint płatności ani POS. Backend ecommerce, billingowy albo POS decyduje, że potwierdzenie istnieje, a następnie wysyła treść do gPdf jako DocumentRequest albo jako dane dla opublikowanego szablonu.
Warstwa renderowania powinna pozostać deterministyczna. Jeśli konsultant obsługi poprosi ponownie o to samo potwierdzenie, Twój system może odtworzyć dane źródłowe albo zwrócić wcześniej zapisany PDF zgodnie z polityką retencji.
Ścieżka szablonu dla powtarzalnych potwierdzeń
Układy potwierdzeń zwykle szybko się stabilizują. Po zatwierdzeniu projektu
opublikuj szablon i wywołuj POST /api/v1/template-render z polami
potwierdzenia. Dzięki temu systemy płatnicze koncentrują się na danych, a
odpowiedzialność za układ pozostaje w jednym miejscu.
FAQ
- Czy gPdf może obliczyć sumę potwierdzenia?
- Nie. System płatniczy albo handlowy odpowiada za sumy, rabaty, podatki i stan zwrotu. gPdf renderuje wartości, które wyślesz.
- Czy potwierdzenia powinny używać JSON Render czy Template Render?
- Użyj JSON Render podczas projektowania układu. Użyj Template Render, gdy układ potwierdzenia i kontrakt pól są stabilne.
- Czy potwierdzenie może zawierać kod QR?
- Tak. gPdf obsługuje elementy kodów QR w wyjściu PDF. Twój system odpowiada za URL albo dane zakodowane w kodzie QR.
- Czy to jest to samo co E-Invoice API?
- Nie. Zwykłe PDF potwierdzeń używają JSON Render albo Template Render. Pakowanie Factur-X i ZUGFeRD używa endpointu E-Invoice Render.