API per PDF di fattura per sistemi di fatturazione e finance
Genera PDF di fatture ordinarie da dati di fatturazione con JSON Render o Template Render, mantenendo logica fiscale e contabile nel vostro sistema.
/api/v1/pdf/render Trasformare i dati fattura provenienti da un sistema di fatturazione, ERP o SaaS in una fattura PDF leggibile, mantenendo numerazione, calcoli fiscali, stato del pagamento e semantica contabile nel sistema chiamante.
Quando usare questa API
- Vi servono PDF di fatture ordinarie per clienti, ricevute, rendiconti o esportazioni contabili.
- Il vostro sistema possiede già numeri fattura, calcolo fiscale, righe documento e stato del pagamento.
- Volete tabelle, totali, metadati e impostazioni PDF/A opzionali senza eseguire un browser.
- Volete un contratto template_id per layout fattura ripetuti.
Cosa non sostituisce
- Vi serve un pacchetto di fattura elettronica legale come Factur-X o ZUGFeRD. Usate E-Invoice Render.
- Vi aspettate che gPdf calcoli imposte, validi regole contabili o riconcili pagamenti.
- Volete convertire HTML arbitrario di fattura invece di usare JSON strutturato o template.
Quale endpoint chiamare
/api/v1/pdf/render
JSON Render è il percorso predefinito per questo flusso.
/api/v1/template-render
Usalo quando il flusso richiede l'API collegata, un contratto di template o una verifica delle capacità.
/api/v1/e-invoice/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 - intestazione fattura e totale minimi.
{
"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
}
]
}
]
}
Cosa gestisce gPdf
- Rendering di PDF di fattura da pagine JSON o dati template.
- Testo, tabelle, blocchi totali, paginazione, metadati e output PDF/A opzionale.
- Template Render per layout fattura stabili usati da più sistemi.
- Risposta PDF binaria ed envelope di errore API coerente.
Cosa controlla il tuo sistema
- Numeri fattura, stato del pagamento, calcolo fiscale, sconti, note di credito e significato contabile.
- Dati cliente ed emittente, mappatura righe, valute e regole di arrotondamento.
- Conservazione, consegna, email, link di pagamento e riconciliazione con il sistema contabile.
Checklist di produzione
- Confermate che ogni campo visibile della fattura sia mappato ai dati sorgente di fatturazione.
- Testate overflow delle righe, nomi cliente lunghi, fatture multipagina e totali.
- Decidete se il layout appartiene a JSON Render o a un template pubblicato.
- Tenete la generazione di PDF di fatture ordinarie separata dal packaging di fattura elettronica legale.
- Salvate request ID e nomi file di output insieme ai record fattura.
Limiti della promessa
- I PDF di fatture ordinarie non equivalgono a mandati legali di fattura elettronica.
- gPdf renderizza il documento fattura; non calcola imposte né stato contabile.
- L'output Factur-X / ZUGFeRD appartiene a POST /api/v1/e-invoice/render.
Fatture ordinarie rispetto a fatture elettroniche
Una fattura PDF ordinaria è il documento che il cliente legge. Può essere generata da JSON Render o Template Render. Il vostro sistema decide numero fattura, imposte, righe, valuta e stato del pagamento; gPdf renderizza poi il PDF visibile.
Una fattura elettronica legale è diversa. Factur-X e ZUGFeRD combinano una
fattura leggibile in PDF/A-3b con XML CII EN 16931 incorporato. Usate
POST /api/v1/e-invoice/render per quel pacchetto.
Template Render è di solito l’endpoint di produzione
I team finance raramente vogliono che ogni servizio ricostruisca coordinate e
layout di fattura. Il percorso comune è progettare la fattura una volta,
pubblicarla come template e fornire ai sistemi chiamanti un template_id
stabile più uno schema dati. JSON Render resta utile per layout personalizzati,
strumenti interni e prototipazione dei template.
Mantenete a monte la logica contabile
gPdf dovrebbe ricevere valori finali da mostrare, non decisioni contabili ancora aperte. Calcolate imposte, sconti, arrotondamenti, stato del pagamento e idoneità della fattura prima di chiamare l’API di rendering. Questo rende deterministico l’output PDF e mantiene il sistema finanziario come fonte autorevole.
FAQ
- Un PDF di fattura è la stessa cosa di una fattura elettronica?
- No. Una fattura PDF ordinaria è un output leggibile da persone. Una fattura elettronica Factur-X o ZUGFeRD incorpora anche XML CII EN 16931 dentro un wrapper PDF/A-3b.
- Quale endpoint usare per fatture ripetute?
- Usate Template Render quando il layout fattura è stabile e i sistemi chiamanti devono inviare solo template_id più data. Usate JSON Render quando il codice possiede il layout.
- gPdf calcola le imposte?
- No. Il vostro sistema di fatturazione o contabilità calcola imposte, totali, sconti e stato del pagamento prima di inviare i dati di rendering.
- I PDF di fattura possono usare PDF/A?
- Sì, JSON Render supporta impostazioni PDF/A. Usate E-Invoice Render specificamente quando la fattura deve essere confezionata come Factur-X o ZUGFeRD.