API de JSON a PDF para generación estructurada de documentos
Convierta datos estructurados JSON DocumentRequest en PDF con páginas, coordenadas, texto, tablas, códigos de barras, metadatos y ajustes PDF/A.
/api/v1/pdf/render Convertir datos estructurados de aplicación en documentos PDF deterministas sin ejecutar un navegador, enviar HTML/CSS ni almacenar archivos de clientes. Su sistema envía páginas, elementos, coordenadas, ajustes y contenido empresarial; gPdf devuelve una respuesta application/pdf.
Cuándo usar esta API
- Su backend ya tiene datos estructurados y necesita una respuesta PDF.
- Quiere páginas, coordenadas, elementos, códigos de barras y ajustes explícitos en lugar de maquetación HTML.
- Necesita salida repetible para facturas, etiquetas, informes, estados de cuenta o paquetes generados.
- Quiere probar datos en el Playground antes de poner un token en producción.
Qué no sustituye
- Necesita conversión HTML-to-PDF arbitraria. gPdf usa JSON DocumentRequest, no un DOM de navegador.
- Su equipo quiere un contrato `template_id` estable. Use Template Render después de publicar el diseño.
- Necesita empaquetado de factura electrónica Factur-X o ZUGFeRD. Use el endpoint E-Invoice Render.
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.
Solicitud mínima
POST /api/v1/pdf/render - DocumentRequest JSON de una página.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Hello from gPdf",
"style": {
"font_size": 18,
"font_family": "NotoSans-Regular"
}
}
]
}
]
}
Qué gestiona gPdf
- Renderizado DocumentRequest desde páginas y elementos.
- Texto, tablas, imágenes, códigos de barras vectoriales, líneas, formas, marcas de agua, metadatos y ajustes PDF/A.
- Incrustación de fuentes y fallback para latín, CJK, scripts con emoji y otros scripts soportados.
- Respuesta PDF binaria con el envoltorio compartido de códigos de error de gPdf en caso de fallo.
Qué controla su sistema
- Datos empresariales, mapeo de campos y semántica del documento.
- IDs de solicitud, estrategia de reintento e idempotencia, nombres de archivo y almacenamiento después de la respuesta.
- Cualquier regla fiscal, de factura, transportista, cumplimiento o cliente antes del renderizado.
Checklist de producción
- Genere y pase un X-Request-Id para trazabilidad.
- Valide los datos contra OpenAPI o la documentación antes de enviar tráfico real.
- Mantenga la URL base de la API configurable y guarde el bearer token fuera del código fuente.
- Decida si la salida debe ser inline o en modo attachment.
- Añada pruebas golden-PDF para diseños críticos, de modo que los cambios de plantilla o datos sean visibles.
Límites de la promesa
- Esto no es HTML-to-PDF y no ejecuta Chromium.
- La API renderiza el documento que usted describe; no infiere significado legal o empresarial desde sus datos.
- Para diseños repetidos, Template Render suele ser el mejor contrato público.
Cómo encaja el flujo JSON Render
JSON Render es la ruta pública de renderizado de menor nivel. Su aplicación envía directamente la estructura del documento: tamaño de página, elementos, coordenadas, estilos, metadatos, modo de salida y ajustes PDF/A opcionales. Es la capa adecuada cuando el diseño del documento se genera por código o cuando su equipo quiere control a nivel de píxel sobre el PDF.
El contrato de API es explícito. Si su sistema envía un elemento de texto, gPdf renderiza un elemento de texto. Si envía un elemento de código de barras, gPdf dibuja el código de barras como contenido PDF vectorial. gPdf no lee intención empresarial desde los datos ni decide si un número de factura, valor de seguimiento de transportista o campo fiscal es correcto.
Cuándo pasar a Template Render
Si el mismo diseño se usa repetidamente entre sistemas, publíquelo como
plantilla y llame a POST /api/v1/template-render con template_id más
data[]. Esto saca la propiedad del diseño de cada cliente y da a su backend
ERP, OMS, WMS o SaaS un contrato de campos estable.
Use JSON Render para creación de diseños, documentos puntuales y documentos programáticos. Use Template Render cuando el diseño esté fijo y lo único que cambia por solicitud sean los datos empresariales.
Forma de producción
En producción, trate una solicitud PDF como cualquier otra llamada de API importante: incluya un ID de solicitud, configure timeout, haga que los reintentos sean idempotentes, registre los metadatos de respuesta y almacene el PDF devuelto solo en su propio sistema si la retención es necesaria. La ruta de renderizado gPdf es stateless después de una respuesta estándar de renderizado.
FAQ
- ¿Es una API HTML-to-PDF?
- No. gPdf acepta un JSON DocumentRequest estructurado con páginas, elementos, coordenadas y ajustes. No ejecuta un navegador ni HTML/CSS arbitrario.
- ¿Qué endpoint debo llamar primero?
- Empiece con POST /api/v1/pdf/render cuando quiera control directo del diseño. Pase a POST /api/v1/template-render cuando el diseño deba convertirse en un contrato `template_id` estable.
- ¿La API devuelve un PDF directamente?
- Sí. Un renderizado correcto devuelve application/pdf. Los errores usan el envoltorio JSON compartido con un código API-XXX y req_id.
- ¿Puedo probar sin construir una integración?
- Use el Playground de gPdf para probar datos JSON de forma interactiva y luego lleve la misma forma DocumentRequest a su cliente backend.