API de facturas PDF para sistemas de facturación y finanzas
Genere facturas PDF ordinarias desde datos de facturación con JSON Render o Template Render, manteniendo la lógica fiscal y contable en su sistema.
/api/v1/pdf/render Convertir datos de factura de un sistema de facturación, ERP o SaaS en una factura PDF legible, manteniendo numeración, impuestos, estado de pago y semántica contable dentro del sistema que llama.
Cuándo usar esta API
- Necesita facturas PDF ordinarias para clientes, recibos, estados de cuenta o exportaciones contables.
- Su sistema ya controla números de factura, cálculo de impuestos, partidas y estado de pago.
- Quiere tablas, totales, metadatos y ajustes opcionales de PDF/A sin ejecutar un navegador.
- Quiere un contrato `template_id` para diseños de factura repetidos.
Qué no sustituye
- Necesita un paquete legal de factura electrónica como Factur-X o ZUGFeRD. Use E-Invoice Render.
- Espera que gPdf calcule impuestos, valide reglas contables o concilie pagos.
- Quiere convertir facturas HTML arbitrarias en lugar de usar JSON estructurado o plantillas.
Qué endpoint llamar
/api/v1/pdf/render
JSON Render es la ruta predeterminada 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
POST /api/v1/pdf/render - encabezado y total mínimos de una factura.
{
"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 de facturas PDF desde páginas JSON o datos de plantilla.
- Texto, tablas, bloques de totales, paginación, metadatos y salida PDF/A opcional.
- Template Render para diseños de factura estables usados por varios sistemas.
- Respuesta PDF binaria y envoltorio de errores de API consistente.
Qué controla su sistema
- Números de factura, estado de pago, cálculo de impuestos, descuentos, créditos y significado contable.
- Datos de cliente y emisor, mapeo de partidas, monedas y reglas de redondeo.
- Retención, entrega, email, enlaces de pago y conciliación con el sistema contable.
Checklist de producción
- Confirme que cada campo visible de la factura se mapea a datos fuente de facturación.
- Pruebe desbordes de partidas, nombres de cliente largos, facturas multipágina y totales.
- Decida si el diseño pertenece a JSON Render o a una plantilla publicada.
- Mantenga la generación de facturas PDF ordinarias separada del empaquetado legal de factura electrónica.
- Guarde IDs de solicitud y nombres de archivo de salida con sus registros de factura.
Límites de la promesa
- Las facturas PDF ordinarias no son lo mismo que los mandatos legales de factura electrónica.
- gPdf renderiza el documento de factura; no calcula impuestos ni estado contable.
- La salida Factur-X / ZUGFeRD corresponde a POST /api/v1/e-invoice/render.
Facturas ordinarias frente a facturas electrónicas
Una factura PDF ordinaria es el documento que lee su cliente. Puede generarse con JSON Render o Template Render. Su sistema decide el número de factura, los impuestos, las partidas, la moneda y el estado de pago; después gPdf renderiza el PDF visible.
Una factura electrónica legal es diferente. Factur-X y ZUGFeRD combinan una
factura PDF/A-3b legible con XML CII EN 16931 incrustado. Use
POST /api/v1/e-invoice/render para ese paquete.
Template Render suele ser el endpoint de producción
Los equipos financieros rara vez quieren que cada servicio reconstruya las
coordenadas de la factura. La ruta habitual es diseñar la factura una vez,
publicarla como plantilla y entregar a los clientes un template_id estable
más un esquema de datos. JSON Render sigue siendo útil para diseños
personalizados, herramientas internas y prototipos de plantilla.
Mantenga la lógica contable aguas arriba
gPdf debe recibir valores finales para mostrar, no decisiones contables sin resolver. Calcule impuestos, descuentos, redondeos, estado de pago y elegibilidad de la factura antes de llamar a la API de renderizado. Así la salida PDF es determinista y el sistema financiero sigue siendo la fuente de referencia.
FAQ
- ¿Una factura PDF es lo mismo que una factura electrónica?
- No. Una factura PDF ordinaria es salida legible por humanos. Una factura electrónica Factur-X o ZUGFeRD también incrusta XML CII EN 16931 dentro de un contenedor PDF/A-3b.
- ¿Qué endpoint deberían usar las facturas repetidas?
- Use Template Render cuando el diseño de factura sea estable y los clientes solo deban enviar `template_id` más `data`. Use JSON Render cuando el código controle el diseño.
- ¿gPdf calcula impuestos?
- No. Su sistema de facturación o contabilidad calcula impuestos, totales, descuentos y estado de pago antes de enviar los datos de renderizado.
- ¿Las facturas PDF pueden usar PDF/A?
- Sí, JSON Render admite ajustes PDF/A. Use E-Invoice Render específicamente cuando la factura deba empaquetarse como Factur-X o ZUGFeRD.