API de facturas ZUGFeRD para sistemas de producción
Genera facturas ZUGFeRD desde datos estructurados del backend, sin navegador, con una frontera clara entre el PDF que renderiza gPdf y las reglas de tu sistema.
/api/v1/e-invoice/render Generar facturas ZUGFeRD como PDF reproducible desde datos estructurados del backend. Tu sistema conserva la lógica de negocio; gPdf se encarga del renderizado PDF.
Cuándo usar esta API
- Tu backend ya tiene los datos de facturas ZUGFeRD y necesita una respuesta PDF estable.
- Quieres evitar Chromium o HTML-to-PDF para documentos operativos.
- Necesitas salida repetible para reimpresiones, auditoría o lotes.
Qué no sustituye
- Necesitas que gPdf compre portes, liquide impuestos, cree pedidos externos o actúe como sistema fiscal.
- Necesitas reemplazar la validación de datos, la lógica de negocio o las integraciones con marketplaces.
Qué endpoint llamar
/api/v1/e-invoice/render
E-Invoice Render es la ruta por defecto 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
/api/v1/e-invoice/render - facturas 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
- Renderizado PDF de facturas ZUGFeRD desde requests estructurados.
- Texto, tablas, líneas, códigos de barras, páginas, metadatos y opciones de salida según el request.
- Salida determinista para reintentos, reimpresiones y auditoría.
Qué controla tu sistema
- Datos correctos de facturas ZUGFeRD, reglas de negocio y estado operativo.
- Autenticación, persistencia, workflows externos y validación con receptores finales.
Checklist de producción
- Prueba con datos reales y con los sistemas receptores del flujo.
- Guarda request IDs y evidencias para soporte, auditoría y reimpresión.
- Convierte el layout aprobado en template cuando varios sistemas deban reutilizarlo.
Límites de la promesa
- gPdf usa el endpoint público de e-invoice para Factur-X / ZUGFeRD PDF/A-3b.
- Portales fiscales, PDP, SDI, KSeF, ZATCA, IRP, Peppol y obligaciones legales quedan fuera.
- Tu sistema conserva datos de comprador, impuestos, routing y criterio legal local.
Forma de la API
API de facturas ZUGFeRD es un workflow de producción sobre las APIs públicas de gPdf. El request describe datos, layout, settings y las partes PDF que deben renderizarse. gPdf genera el PDF; tu sistema mantiene la semántica del evento de negocio.
Elección de endpoint
Para este flujo, el endpoint por defecto es /api/v1/e-invoice/render. Usa Template Render cuando el layout ya esté aprobado y se reutilice entre sistemas. Usa E-Invoice Render solo si necesitas empaquetado Factur-X / ZUGFeRD PDF/A-3b con EN 16931 CII XML embebido.
Validación antes de producción
Valida facturas ZUGFeRD con datos reales y con los sistemas que lo consumirán. Conserva request IDs, salida renderizada y evidencias de validación para soporte, auditoría y reimpresión.
FAQ
- ¿Es un endpoint separado?
- API de facturas ZUGFeRD mapea el flujo a una API pública de gPdf. La página explica qué ruta llamar y qué debe aportar tu request.
- ¿Cubre redes locales de clearance?
- No. gPdf renderiza y empaqueta el PDF/e-invoice; la presentación fiscal y el routing legal quedan en tu sistema.
- ¿Puedo seguir usando JSON Render?
- Sí para PDFs ordinarios. Usa E-Invoice Render cuando el resultado deba incluir el paquete estructurado descrito por la API pública.