API ZUGFeRD para facturas híbridas PDF/A-3b
Genere facturas ZUGFeRD PDF/A-3b con XML CII EN 16931 incrustado usando el endpoint público gPdf E-Invoice Render.
/api/v1/e-invoice/render Empaquetar la salida PDF de una factura como ZUGFeRD PDF/A-3b con XML CII EN 16931 incrustado después de que su ERP o sistema de facturación haya preparado los datos correctos de la factura.
Cuándo usar esta API
- Necesita salida ZUGFeRD nativa desde el endpoint público E-Invoice Render.
- Su sistema ya tiene XML CII EN 16931 válido para la factura.
- Necesita empaquetado PDF/A-3b con metadatos ZUGFeRD y cableado de archivo asociado.
- Necesita una página hermana clara para las páginas más amplias de factura electrónica y Factur-X.
Qué no sustituye
- Necesita generación nativa XRechnung o envío a portales.
- Necesita que gPdf calcule impuestos, infiera semántica de factura o cree XML desde registros contables.
- Necesita estándares no listados en el contrato público OpenAPI.
Qué endpoint llamar
/api/v1/e-invoice/render
E-Invoice Render es la ruta predeterminada para este flujo.
/api/v1/e-invoice/capabilities
Úsalo cuando el flujo necesite la ruta API relacionada, un contrato de plantilla o una consulta de capacidades.
Solicitud mínima
POST /api/v1/e-invoice/render - forma mínima de un paquete ZUGFeRD.
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "zugferd",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "ZUGFeRD invoice",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
Qué gestiona gPdf
- Empaquetado ZUGFeRD mediante E-Invoice Render.
- Manejo del perfil PDF/A-3b para salida de factura híbrida.
- Incrustación de XML CII como archivo asociado con metadatos ZUGFeRD.
- Comportamiento de entrega PDF inline o por objeto según la documentación.
Qué controla su sistema
- Corrección del XML CII EN 16931, datos de factura, lógica fiscal y semántica de comprador y vendedor.
- Validación externa, requisitos del destinatario, envío a portales e interpretación legal.
- Comportamiento de reintentos, almacenamiento, evidencia de auditoría y entrega al cliente.
Checklist de producción
- Defina settings.e_invoice.standard = zugferd y settings.e_invoice.profile = en16931.
- Use XML CII con format = cii y encoding = utf8.
- Defina settings.profile como pdfa-3b u omítalo para que se aplique el valor por defecto de factura electrónica.
- Valide el PDF devuelto con su flujo de validación ZUGFeRD.
- Mantenga el trabajo de XRechnung o envío a portales fuera de este endpoint.
Límites de la promesa
- Esta página cubre salida ZUGFeRD mediante E-Invoice Render.
- No afirma generación nativa XRechnung.
- Su sistema controla los datos empresariales de la factura y la validez del XML.
ZUGFeRD usa la ruta de renderizado de factura electrónica
ZUGFeRD no es un endpoint raíz separado. Se selecciona mediante el campo
settings.e_invoice.standard en POST /api/v1/e-invoice/render. Se aplica la
misma frontera: gPdf empaqueta la factura híbrida PDF/A-3b; su sistema controla
los hechos de la factura y la validez del XML.
FAQ
- ¿Qué endpoint renderiza ZUGFeRD?
- Use POST /api/v1/e-invoice/render con settings.e_invoice.standard establecido en zugferd.
- ¿Esta página cubre XRechnung?
- No. Esta página se limita al contrato público ZUGFeRD. Aquí no se afirma que XRechnung sea salida nativa.
- ¿gPdf crea el XML CII?
- Su sistema proporciona el XML CII EN 16931 y controla su corrección.
- ¿Puedo verificar el resultado?
- Use su flujo de validación ZUGFeRD y las páginas del validador de gPdf como contexto de validación.