API per fattura elettronica Factur-X e ZUGFeRD PDF/A-3b
Genera fatture elettroniche Factur-X e ZUGFeRD PDF/A-3b con XML CII EN 16931 incorporato tramite l'endpoint pubblico gPdf per e-invoice.
/api/v1/e-invoice/render Confezionare una fattura PDF leggibile da persone e XML CII EN 16931 fornito dal sistema chiamante in una fattura elettronica Factur-X o ZUGFeRD PDF/A-3b validabile da motori di riferimento esterni per PDF/A ed e-invoice.
Quando usare questa API
- Vi serve output Factur-X o ZUGFeRD, non solo una fattura PDF ordinaria.
- Il vostro sistema può fornire XML CII EN 16931 corretto per la fattura.
- Vi servono packaging PDF/A-3b, metadati del file associato e cablaggio XMP e-invoice.
- Volete usare l'endpoint pubblico delle capacità per confermare standard e profili supportati.
Cosa non sostituisce
- Vi serve solo una fattura PDF ordinaria per clienti. Usate JSON Render o Template Render.
- Vi serve output nativo XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e o GST prima che OpenAPI lo elenchi.
- Vi aspettate che gPdf crei XML di fattura legalmente corretto da dati di business incompleti.
Quale endpoint chiamare
/api/v1/e-invoice/render
E-Invoice Render è il percorso predefinito per questo flusso.
/api/v1/e-invoice/capabilities
Usalo quando il flusso richiede l'API collegata, un contratto di template o una verifica delle capacità.
Request minimo
POST /api/v1/e-invoice/render - richiesta Factur-X PDF/A-3b minima.
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "factur_x",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
Cosa gestisce gPdf
- Packaging Factur-X o ZUGFeRD PDF/A-3b tramite POST /api/v1/e-invoice/render.
- Incorporamento dell'XML CII EN 16931 fornito dal sistema chiamante come file associato.
- Metadati del wrapper PDF/A-3b e cablaggio XMP e-invoice specifico dello standard.
- Scoperta delle capacità tramite GET /api/v1/e-invoice/capabilities.
Cosa controlla il tuo sistema
- Semantica di business della fattura, regole fiscali, identificativi acquirente/venditore e correttezza dell'XML EN 16931.
- Scelta tra Factur-X e ZUGFeRD in base al processo del destinatario.
- Test di accettazione esterni con destinatario, sistema di automazione AP o processo locale di conformità.
Checklist di produzione
- Chiamate /api/v1/e-invoice/capabilities prima di assumere uno standard o profilo.
- Validate l'XML CII EN 16931 prima di incorporarlo.
- Passate l'output in /validator/ o nella vostra pipeline con motori di riferimento.
- Tenete separati nel codice generazione di fatture PDF ordinarie e packaging legale e-invoice.
- Registrate request ID, standard, profilo, versione sorgente XML ed evidenze di validazione.
Limiti della promessa
- L'output pubblico nativo per e-invoice è Factur-X / ZUGFeRD con XML CII EN 16931.
- Altri nomi nazionali di fatturazione elettronica sono contesto di mercato salvo quando OpenAPI li elenca come standard supportati.
- gPdf confeziona XML fornito dal sistema chiamante; il vostro sistema resta responsabile della correttezza business dell'XML.
Un endpoint per il pacchetto e-invoice
L’endpoint e-invoice esiste perché questo processo non è solo “renderizzare una fattura PDF”. Deve produrre un wrapper PDF/A-3b con i metadati corretti del file associato e XMP specifico dello standard, incorporando l’XML CII EN 16931 fornito dal sistema chiamante.
Chiamate POST /api/v1/e-invoice/render quando l’output richiesto è Factur-X o
ZUGFeRD. Usate GET /api/v1/e-invoice/capabilities quando l’integrazione deve
confermare standard, profili, tipi documento e formati XML supportati prima di
inviare lavoro.
Cosa resta fuori da gPdf
La semantica XML resta vostra responsabilità. gPdf non può sapere se un numero fattura è legalmente corretto, se un importo fiscale è corretto, se un identificativo acquirente corrisponde al trading partner o se uno specifico destinatario accetterà una variante del processo di business. Generate e validate l’XML a monte, poi usate gPdf per packaging PDF/A-3b e rendering.
Tenete i termini di roadmap fuori dalle dichiarazioni di supporto nativo
È corretto discutere XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e o GST come contesto di mercato. Non presentate questi nomi come output nativo pubblico salvo quando il contratto delle capacità OpenAPI li elenca.
FAQ
- Quali standard e-invoice sono output pubblico nativo oggi?
- L'output pubblico nativo è Factur-X e ZUGFeRD PDF/A-3b con XML CII EN 16931 incorporato. Verificate /api/v1/e-invoice/capabilities per il contratto corrente.
- gPdf genera per me l'XML EN 16931?
- No. Il vostro sistema fornisce il contenuto XML. gPdf lo confeziona nel wrapper e-invoice PDF/A-3b con i metadati di file associato richiesti.
- Posso inviare settings.e_invoice a JSON Render?
- No. Il packaging e-invoice appartiene a POST /api/v1/e-invoice/render. La documentazione pubblica indica che settings.e_invoice è specifico di questa rotta.
- Come devo validare l'output?
- Usate il validator gPdf o la vostra pipeline con motori di riferimento per controllare sia il livello PDF/A sia il livello XML e-invoice incorporato.