API per generazione PDF in batch per code e job
Generate molti PDF tramite percorsi JSON Render o Template Render adatti alle code, mentre il vostro sistema possiede suddivisione, retry, idempotenza e conservazione.
/api/v1/template-render Renderizzare molti PDF da una coda o da un job pianificato dividendo il lavoro in richieste sicure, inviando a gPdf ogni documento o elemento data del template, e conservando o consegnando il PDF restituito nel vostro sistema.
Quando usare questa API
- Dovete generare fatture, estratti conto, etichette o report in un batch pianificato o guidato da eventi.
- Avete un template stabile e potete inviare più elementi data entro i limiti dell'endpoint.
- Vi serve rendering adatto alle code senza eseguire browser worker.
- Potete gestire deduplicazione, retry e conservazione dell'output.
Cosa non sostituisce
- Vi serve che gPdf sia il vostro scheduler batch, sistema di coda, storage o registro di idempotenza.
- Vi servono header di rate limit pubblicati o un contratto server-side basato su idempotency-key.
- Vi serve una singola richiesta illimitata per renderizzare ogni documento di una campagna.
Quale endpoint chiamare
/api/v1/template-render
Template Render è il percorso predefinito per questo flusso.
/api/v1/pdf/render
Usalo quando il flusso richiede l'API collegata, un contratto di template o una verifica delle capacità.
Request minimo
POST /api/v1/template-render - piccolo batch con due elementi data di fattura.
{
"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": []
}
]
}
Cosa gestisce gPdf
- Rendering PDF per ogni richiesta JSON Render o Template Render.
- Array data di Template Render entro i limiti pubblici documentati.
- Risposte di rendering stateless e rapide, adatte a worker di coda.
- Comportamento condiviso per request ID ed envelope di errore.
Cosa controlla il tuo sistema
- Disegno della coda, suddivisione in blocchi, concorrenza, retry, deduplicazione e conservazione dell'output.
- Selezione degli oggetti di business, scelta del template e processo di consegna.
- Policy di backoff, alerting e recupero dopo un errore parziale.
Checklist di produzione
- Suddividete il lavoro in modo che ogni richiesta resti entro i limiti documentati per elementi e dimensione della richiesta.
- Generate un X-Request-Id per ogni richiesta e associatelo al vostro job ID.
- Ritentate solo errori di rete o 5xx con backoff esponenziale limitato.
- Non ritentate errori 4xx di verifica senza cambiare i dati inviati.
- Conservate PDF di output o dati sorgente secondo la vostra policy di retention.
Limiti della promessa
- gPdf è l'API di rendering, non il livello di coda o storage.
- L'API pubblica oggi non pubblica header di rate limit né chiavi di idempotenza server-side.
- Il vostro sistema deve rendere sicuri i retry.
La generazione in batch è un pattern di integrazione
La generazione PDF in batch non è un endpoint separato. È il modo in cui la vostra coda usa le API pubbliche di rendering. Mantenete i job piccoli, osservabili e sicuri da ritentare.
Per layout ripetuti, Template Render di solito offre il contratto più pulito. Per documenti programmatici con layout personalizzati, JSON Render resta disponibile.
FAQ
- gPdf offre una API per job batch?
- No, non è esposto uno scheduler batch separato. Usate JSON Render o Template Render dal vostro sistema di code o worker.
- Template Render può accettare più elementi data?
- Sì, entro i limiti dell'endpoint pubblico. Dividete i job più grandi su più richieste.
- Chi possiede i retry?
- Il vostro sistema possiede retry, backoff, deduplicazione e idempotenza. gPdf riecheggia i request ID per tracciabilità.
- Posso renderizzare molti layout diversi in una richiesta?
- Usate richieste separate quando layout o template ID sono diversi. Mantenete ogni richiesta semplice e tracciabile.