È una API HTML-to-PDF?

No. gPdf accetta un DocumentRequest JSON strutturato con pagine, elementi, coordinate e impostazioni. Non esegue un browser né HTML/CSS arbitrario.

Quale endpoint dovrei chiamare per primo?

Iniziate con POST /api/v1/pdf/render quando volete controllo diretto del layout. Passate a POST /api/v1/template-render quando il layout deve diventare un contratto template_id stabile.

L'API restituisce direttamente un PDF?

Sì. Un rendering riuscito restituisce application/pdf. Gli errori usano l'envelope JSON condiviso con codice API-XXX e req_id.

Posso testare senza costruire un'integrazione?

Usate gPdf Playground per provare richieste JSON in modo interattivo, poi spostate la stessa forma DocumentRequest nel client del vostro backend.

Flussi per sviluppatori

API JSON a PDF per la generazione strutturata di documenti

Trasforma richieste DocumentRequest JSON strutturate in PDF con pagine, coordinate, testo, tabelle, codici a barre, metadati e impostazioni PDF/A.

API PRINCIPALE JSON Render

ENDPOINT /api/v1/pdf/render

SISTEMI backend SaaS / API worker / agente AI / coda di job

Provare nel Playground Leggere la documentazione

Lavoro da svolgere

Convertire dati applicativi strutturati in documenti PDF deterministici senza eseguire un browser, distribuire HTML/CSS o conservare file dei clienti. Il vostro sistema invia pagine, elementi, coordinate, impostazioni e contenuto di business; gPdf restituisce una risposta application/pdf.

Quando usare questa API

Il vostro backend ha già dati strutturati e deve ottenere una risposta PDF.
Preferite pagine, coordinate, elementi, codici a barre e impostazioni esplicite invece di un layout HTML.
Vi serve output ripetibile per fatture, etichette, report, estratti conto o pacchetti generati.
Volete testare le richieste nel Playground prima di usare un token in produzione.

Cosa non sostituisce

Vi serve conversione HTML-to-PDF arbitraria. gPdf usa JSON DocumentRequest, non un browser DOM.
Il vostro team vuole un contratto stabile basato su template_id. Usate Template Render dopo la pubblicazione del layout.
Vi serve packaging e-invoice Factur-X o ZUGFeRD. Usate l'endpoint E-Invoice Render.

Quale endpoint chiamare

PRIMARIO

/api/v1/pdf/render

JSON Render è il percorso predefinito per questo flusso.

SECONDARIO 1

/api/v1/template-render

Usalo quando il flusso richiede l'API collegata, un contratto di template o una verifica delle capacità.

Request minimo

POST /api/v1/pdf/render - DocumentRequest JSON di una pagina.

{
  "pages": [
    {
      "size": "a4",
      "elements": [
        {
          "type": "text",
          "x": 20,
          "y": 24,
          "content": "Hello from gPdf",
          "style": {
            "font_size": 18,
            "font_family": "NotoSans-Regular"
          }
        }
      ]
    }
  ]
}

Cosa gestisce gPdf

Rendering di DocumentRequest da pagine ed elementi.
Testo, tabelle, immagini, codici a barre vettoriali, linee, forme, watermark, metadati e impostazioni PDF/A.
Incorporamento font e fallback per Latin, CJK, script compatibili con emoji e altri script supportati.
Risposta PDF binaria con envelope condiviso dei codici errore gPdf in caso di errore.

Cosa controlla il tuo sistema

Dati di business, mappatura dei campi e semantica del documento.
Request ID, strategia di retry e idempotenza, nomi file e conservazione dopo la risposta.
Qualsiasi regola fiscale, di fattura, vettore, conformità o specifica del cliente prima del rendering.

Checklist di produzione

Generate e passate un X-Request-Id per tracciabilità.
Verificate le richieste contro OpenAPI o documentazione prima di inviare traffico live.
Mantenete configurabile l'URL base dell'API e conservate il bearer token fuori dal codice sorgente.
Decidete se l'output deve essere inline o restituito come allegato.
Aggiungete test golden-PDF per i layout critici, così le modifiche a template o dati restano visibili.

Limiti della promessa

Questa non è una soluzione HTML-to-PDF e non esegue Chromium.
L'API renderizza il documento che descrivete; non deduce significato legale o di business dai vostri dati.
Per layout ripetuti, Template Render è di solito il contratto pubblico più adatto.

Come si inserisce il percorso JSON Render

JSON Render è il percorso pubblico di rendering di livello più basso. La vostra applicazione invia direttamente la struttura del documento: dimensione pagina, elementi, coordinate, stili, metadati, modalità di output e impostazioni PDF/A opzionali. È il livello giusto quando il layout del documento è generato da codice o quando il team vuole controllo puntuale sul PDF.

Il contratto API è esplicito. Se il vostro sistema invia un elemento testo, gPdf renderizza un elemento testo. Se invia un elemento codice a barre, gPdf lo disegna come contenuto PDF vettoriale. gPdf non legge intenzioni di business dai dati inviati e non decide se un numero fattura, un valore di tracking del vettore o un campo fiscale sia corretto.

Quando passare a Template Render

Se lo stesso layout viene usato ripetutamente da più sistemi, pubblicatelo come template e chiamate POST /api/v1/template-render con template_id più data[]. In questo modo la responsabilità del layout non resta in ogni sistema chiamante e il vostro ERP, OMS, WMS o backend SaaS ottiene un contratto di campi stabile.

Usate JSON Render per creare layout, documenti una tantum e documenti programmatici. Usate Template Render quando il layout è fisso e l’unica parte che cambia a ogni richiesta sono i dati di business.

Forma di produzione

In produzione, trattate una richiesta PDF come qualsiasi altra chiamata API importante: includete un request ID, impostate un timeout, rendete idempotenti i retry, registrate i metadati della risposta e conservate il PDF restituito solo nel vostro sistema se è richiesta retention. Il percorso di rendering gPdf è stateless dopo una risposta standard.

FAQ

È una API HTML-to-PDF?: No. gPdf accetta un DocumentRequest JSON strutturato con pagine, elementi, coordinate e impostazioni. Non esegue un browser né HTML/CSS arbitrario.
Quale endpoint dovrei chiamare per primo?: Iniziate con POST /api/v1/pdf/render quando volete controllo diretto del layout. Passate a POST /api/v1/template-render quando il layout deve diventare un contratto template_id stabile.
L'API restituisce direttamente un PDF?: Sì. Un rendering riuscito restituisce application/pdf. Gli errori usano l'envelope JSON condiviso con codice API-XXX e req_id.
Posso testare senza costruire un'integrazione?: Usate gPdf Playground per provare richieste JSON in modo interattivo, poi spostate la stessa forma DocumentRequest nel client del vostro backend.