API de generación PDF por lotes para colas y trabajos
Genere muchos PDF mediante flujos JSON Render o Template Render seguros para colas, mientras su sistema controla particionado, reintentos, idempotencia y almacenamiento.
/api/v1/template-render Renderizar muchos PDF desde una cola o trabajo programado dividiendo el trabajo en solicitudes seguras, enviando cada documento o elemento de datos de plantilla a gPdf y almacenando o entregando el PDF devuelto en su propio sistema.
Cuándo usar esta API
- Necesita generar facturas, estados, etiquetas o informes en un lote programado o disparado por eventos.
- Tiene una plantilla estable y puede enviar varios elementos de datos dentro de los límites del endpoint.
- Necesita renderizado compatible con colas sin ejecutar workers de navegador.
- Puede controlar deduplicación, reintentos y almacenamiento de salida.
Qué no sustituye
- Necesita que gPdf sea su planificador de lotes, cola, sistema de almacenamiento o ledger de idempotencia.
- Necesita headers de rate-limit publicados o un contrato server-side de idempotency-key.
- Necesita una sola solicitud ilimitada que renderice todos los documentos de una campaña.
Qué endpoint llamar
/api/v1/template-render
Template Render es la ruta predeterminada para este flujo.
/api/v1/pdf/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/template-render - lote pequeño con dos elementos de datos de factura.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-101",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer A",
"subtotal": "$50.00",
"total": "$50.00",
"amount_due": "$50.00",
"items": []
},
{
"invoice_number": "INV-2026-102",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer B",
"subtotal": "$75.00",
"total": "$75.00",
"amount_due": "$75.00",
"items": []
}
]
}
Qué gestiona gPdf
- Renderizado PDF para cada solicitud JSON Render o Template Render.
- Arrays `data` de Template Render dentro de los límites públicos documentados.
- Respuestas de renderizado rápidas y stateless, adecuadas para workers de cola.
- Comportamiento compartido de ID de solicitud y envoltorio de errores.
Qué controla su sistema
- Diseño de cola, particionado, concurrencia, reintentos, deduplicación y almacenamiento de salida.
- Selección de objetos empresariales, elección de plantilla y flujo de entrega.
- Política de backoff, alertas y recuperación después de fallos parciales.
Checklist de producción
- Particione el trabajo para que cada solicitud permanezca dentro de los límites documentados de elementos y tamaño.
- Genere un X-Request-Id por solicitud y mapéelo a su ID de trabajo.
- Reintente solo fallos de red o 5xx con backoff exponencial acotado.
- No reintente fallos de validación 4xx sin cambiar los datos.
- Almacene PDF de salida o datos fuente según su política de retención.
Límites de la promesa
- gPdf es la API de renderizado, no la capa de cola ni almacenamiento.
- La API pública no publica hoy headers de rate-limit ni claves de idempotencia server-side.
- Su sistema debe hacer que los reintentos sean seguros.
La generación por lotes es un patrón de integración
La generación PDF por lotes no es un endpoint separado. Es la forma en que su cola usa las APIs públicas de renderizado. Mantenga los trabajos pequeños, observables y seguros ante reintentos.
Para diseños repetidos, Template Render suele ofrecer el contrato más limpio. Para documentos programáticos con diseños personalizados, JSON Render sigue estando disponible.
FAQ
- ¿gPdf proporciona una API de trabajos por lotes?
- No se expone un planificador de lotes separado. Use JSON Render o Template Render desde su propia cola o sistema de workers.
- ¿Template Render acepta varios elementos de datos?
- Sí, dentro de los límites públicos del endpoint. Divida trabajos grandes en varias solicitudes.
- ¿Quién controla los reintentos?
- Su sistema controla reintentos, backoff, deduplicación e idempotencia. gPdf refleja IDs de solicitud para trazabilidad.
- ¿Puedo renderizar muchos layouts distintos en una solicitud?
- Use solicitudes separadas cuando los diseños o `template_id` sean diferentes. Mantenga cada solicitud simple y trazable.