API de factura electrónica para Factur-X y ZUGFeRD PDF/A-3b
Genere facturas electrónicas Factur-X y ZUGFeRD PDF/A-3b con XML CII EN 16931 incrustado mediante el endpoint público de factura electrónica de gPdf.
/api/v1/e-invoice/render Empaquetar una factura PDF legible y XML CII EN 16931 proporcionado por quien llama dentro de una factura electrónica Factur-X o ZUGFeRD PDF/A-3b que pueda validarse con motores externos de referencia PDF/A y factura electrónica.
Cuándo usar esta API
- Necesita salida Factur-X o ZUGFeRD, no solo una factura PDF ordinaria.
- Su sistema puede proporcionar XML CII EN 16931 correcto para la factura.
- Necesita empaquetado PDF/A-3b, metadatos de adjunto y cableado XMP de factura electrónica.
- Quiere que el endpoint público de capacidades confirme estándares y perfiles soportados.
Qué no sustituye
- Solo necesita una factura PDF ordinaria para clientes. Use JSON Render o Template Render.
- Necesita salida nativa XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e o GST antes de que OpenAPI la liste.
- Espera que gPdf cree XML de factura legalmente correcto desde datos empresariales incompletos.
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 - solicitud Factur-X PDF/A-3b mínima.
{
"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" }
}
]
}
]
}
Qué gestiona gPdf
- Empaquetado Factur-X o ZUGFeRD PDF/A-3b mediante POST /api/v1/e-invoice/render.
- Incrustación del XML CII EN 16931 proporcionado por quien llama como archivo asociado.
- Metadatos del contenedor PDF/A-3b y cableado XMP específico de la factura electrónica.
- Descubrimiento de capacidades mediante GET /api/v1/e-invoice/capabilities.
Qué controla su sistema
- Semántica empresarial de la factura, reglas fiscales, identificadores de comprador/vendedor y corrección del XML EN 16931.
- Elección de si Factur-X o ZUGFeRD es adecuado para el flujo del destinatario.
- Pruebas de aceptación externas con el receptor, sistema de automatización AP o proceso local de cumplimiento.
Checklist de producción
- Llame a /api/v1/e-invoice/capabilities antes de asumir un estándar o perfil.
- Valide el XML CII EN 16931 antes de incrustarlo.
- Pase la salida por /validator/ o por su propio pipeline de motores de referencia.
- Mantenga separadas en el código la generación de facturas PDF ordinarias y el empaquetado legal de factura electrónica.
- Registre IDs de solicitud, estándar, perfil, versión de la fuente XML y evidencia de validación.
Límites de la promesa
- La salida pública nativa de factura electrónica es Factur-X / ZUGFeRD con XML CII EN 16931.
- Otros nombres nacionales de factura electrónica son contexto de mercado salvo que OpenAPI los liste como estándares soportados.
- gPdf empaqueta XML proporcionado por quien llama; su sistema sigue siendo responsable de la corrección empresarial del XML.
Un endpoint para el paquete de factura electrónica
El endpoint de factura electrónica existe porque este flujo no es solo “renderizar una factura PDF”. Debe producir un contenedor PDF/A-3b con los metadatos correctos de archivo asociado y XMP específico del estándar, mientras incrusta el XML CII EN 16931 proporcionado por quien llama.
Llame a POST /api/v1/e-invoice/render cuando la salida requerida sea
Factur-X o ZUGFeRD. Use GET /api/v1/e-invoice/capabilities cuando su
integración quiera confirmar estándares, perfiles, tipos de documento y
formatos XML soportados antes de enviar trabajo.
Qué queda fuera de gPdf
La semántica del XML sigue siendo su responsabilidad. gPdf no puede saber si un número de factura es legal, si un importe de impuestos es correcto, si un identificador de comprador coincide con la contraparte o si un receptor concreto aceptará una variante del proceso empresarial. Genere y valide el XML aguas arriba; luego use gPdf para el empaquetado PDF/A-3b y el renderizado.
Mantenga los términos de hoja de ruta fuera de las afirmaciones de soporte nativo
Es válido mencionar XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e o GST como contexto de mercado. No presente esos nombres como salida nativa del renderizador público salvo que el contrato de capacidades OpenAPI los liste.
FAQ
- ¿Qué estándares de factura electrónica son salida pública nativa hoy?
- La salida pública nativa es Factur-X y ZUGFeRD PDF/A-3b con XML CII EN 16931 incrustado. Revise /api/v1/e-invoice/capabilities para el contrato actual.
- ¿gPdf genera el XML EN 16931 por mí?
- No. Su sistema proporciona el contenido XML. gPdf lo empaqueta dentro del contenedor de factura electrónica PDF/A-3b con los metadatos de adjunto requeridos.
- ¿Puedo enviar settings.e_invoice a JSON Render?
- No. El empaquetado de factura electrónica pertenece a POST /api/v1/e-invoice/render. La documentación pública indica que settings.e_invoice es específico de esa ruta.
- ¿Cómo debo validar la salida?
- Use el validador de gPdf o su propio flujo con motores de referencia para comprobar tanto la capa PDF/A como la capa XML de factura electrónica incrustada.