API de facturas PDF para sistemas de producción
Genera facturas PDF 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/pdf/render Generar facturas PDF 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 PDF 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/pdf/render
JSON Render es la ruta por defecto para este flujo.
/api/v1/template-render
Úsalo cuando el flujo necesite la ruta API relacionada, un contrato de plantilla o una consulta de capacidades.
/api/v1/e-invoice/render
Úsalo cuando el flujo necesite la ruta API relacionada, un contrato de plantilla o una consulta de capacidades.
Solicitud mínima
/api/v1/pdf/render - facturas PDF
{
"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
}
]
}
]
}
Qué gestiona gPdf
- Renderizado PDF de facturas PDF 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 PDF, 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 renderiza el PDF desde el request; no reemplaza workflow, base de datos ni validación de producto.
- Tu sistema mantiene semántica de datos, retries, persistencia y aceptación final.
Forma de la API
API de facturas PDF 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/pdf/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 PDF 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 PDF mapea el flujo a una API pública de gPdf. La página explica qué ruta llamar y qué debe aportar tu request.
- ¿Puedo usar templates?
- Sí. Usa JSON Render mientras el layout cambia y Template Render cuando el layout esté aprobado y los callers solo deban enviar datos de negocio.
- ¿Qué debo validar antes de producción?
- Valida con datos reales y con impresoras, escáneres, validadores, contabilidad o marketplaces según el flujo.