API do masowego generowania PDF dla kolejek i zadań
Generuj wiele PDF przez bezpieczne dla kolejek procesy JSON Render albo Template Render, gdy Twój system odpowiada za porcjowanie, retry, idempotencję i przechowywanie.
/api/v1/template-render Renderować wiele PDF z kolejki albo zaplanowanego zadania przez dzielenie pracy na bezpieczne żądania, wysyłanie każdego dokumentu lub elementu danych szablonu do gPdf oraz przechowywanie albo dostarczanie zwróconego PDF we własnym systemie.
Kiedy użyć tej API
- Musisz generować faktury, zestawienia, etykiety albo raporty w partii uruchamianej harmonogramem lub zdarzeniem.
- Masz stabilny szablon i możesz wysłać wiele elementów danych w granicach limitów endpointu.
- Potrzebujesz renderowania przyjaznego dla kolejek bez uruchamiania workerów przeglądarkowych.
- Twój system może odpowiadać za deduplikację, retry i przechowywanie wyników.
Czego nie zastępuje
- Potrzebujesz, aby gPdf był harmonogramem batchy, kolejką, systemem przechowywania albo rejestrem idempotencji.
- Potrzebujesz opublikowanych nagłówków rate-limit albo serwerowego kontraktu idempotency-key.
- Potrzebujesz jednego nieograniczonego żądania, które wyrenderuje każdy dokument w kampanii.
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 - mała partia z dwoma elementami danych faktury.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-101",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer A",
"subtotal": "$50.00",
"total": "$50.00",
"amount_due": "$50.00",
"items": []
},
{
"invoice_number": "INV-2026-102",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer B",
"subtotal": "$75.00",
"total": "$75.00",
"amount_due": "$75.00",
"items": []
}
]
}
Co obsługuje gPdf
- Renderowanie PDF dla każdego żądania JSON Render albo Template Render.
- Tablice danych Template Render w udokumentowanych limitach publicznych.
- Szybkie, bezstanowe odpowiedzi renderowania odpowiednie dla workerów kolejkowych.
- Wspólne zachowanie identyfikatora żądania i koperty błędu.
Co kontroluje Twój system
- Projekt kolejki, porcjowanie, współbieżność, retry, deduplikację i przechowywanie wyników.
- Wybór obiektów biznesowych, dobór szablonu i proces dostarczenia.
- Politykę backoff, alertowanie i odzyskiwanie po częściowej awarii.
Checklist produkcyjny
- Dziel pracę tak, aby każde żądanie mieściło się w udokumentowanych limitach liczby elementów i payloadu.
- Generuj osobny X-Request-Id dla każdego żądania i mapuj go na ID zadania.
- Ponawiaj tylko błędy sieciowe albo 5xx, z ograniczonym exponential backoff.
- Nie ponawiaj błędów walidacji 4xx bez zmiany payloadu.
- Przechowuj wynikowe PDF albo dane źródłowe zgodnie z własną polityką retencji.
Granice deklaracji
- gPdf jest API renderowania, a nie warstwą kolejki ani przechowywania.
- Publiczne API obecnie nie publikuje nagłówków rate-limit ani serwerowych kluczy idempotencji.
- Twój system musi sprawić, że retry będą bezpieczne.
Generowanie batch to wzorzec integracyjny
Masowe generowanie PDF nie jest osobnym endpointem. To sposób, w jaki Twoja kolejka korzysta z publicznych API renderowania. Zadania powinny być małe, obserwowalne i bezpieczne przy retry.
Dla powtarzalnych layoutów Template Render zwykle daje najczystszy kontrakt. Dla dokumentów programowych z niestandardowym layoutem nadal dostępny jest JSON Render.
FAQ
- Czy gPdf udostępnia API zadań batch?
- Nie ma osobnego harmonogramu batch. Wywołuj JSON Render albo Template Render z własnej kolejki lub systemu workerów.
- Czy Template Render może przyjąć wiele elementów danych?
- Tak, w granicach limitów publicznego endpointu. Większe zadania dziel na wiele żądań.
- Kto odpowiada za retry?
- Twój system odpowiada za retry, backoff, deduplikację i idempotencję. gPdf odsyła identyfikatory żądań dla śledzenia.
- Czy mogę renderować wiele różnych layoutów w jednym żądaniu?
- Używaj osobnych żądań, gdy layouty albo template IDs się różnią. Każde żądanie powinno być proste i łatwe do prześledzenia.