Blueprint: API HTML a PDF con Postgres, Chromium y nada más

La generación de documentos PDF a partir de plantillas HTML es un desafío recurrente en aplicaciones empresariales: facturas, informes financieros, certificados, contratos. Cada documento puede variar drásticamente en tamaño y volumen, desde unos pocos kilobytes hasta cientos de megabytes, y el tráfico suele llegar en ráfagas impredecibles. Frente a esto, muchas arquitecturas caen en la tentación de replicar el stack de una gran corporación: Redis, Kafka, Kubernetes, múltiples servicios acoplados. Sin embargo, para equipos pequeños o startups que necesitan aplicaciones a medida, existe un camino más eficiente: una API HTML a PDF basada en Postgres, Chromium y nada más. Este enfoque minimalista, que prioriza la simplicidad operativa y la escalabilidad controlada, se ha convertido en un estándar de facto para quienes entienden que cada dependencia extra es un punto potencial de fallo.

La clave está en usar el mismo Postgres que ya almacena los datos de la aplicación como cola de trabajos asíncronos, gracias a herramientas como pg-boss. No necesitas Redis ni BullMQ; una sola base de datos respalda tanto los datos transaccionales como la planificación de tareas de renderizado. Esto reduce drásticamente la complejidad: una única fuente de verdad, un único sistema que monitorizar y del que hacer copias de seguridad. Para un equipo pequeño, eso significa menos noches de guardia y más tiempo para centrarse en el negocio. Cuando el volumen de peticiones es asimétrico —por ejemplo, 10.000 solicitudes de generación en un minuto pero solo capacidad para procesar 60 PDFs por segundo— la cola actúa como un amortiguador natural, desacoplando la tasa de ingesta de la tasa de procesamiento. Ningún pico se pierde; los trabajos se consumen a su propio ritmo.

El manejo de la memoria es otro punto crítico. Un documento de 400 MB no puede cargarse completo en RAM sin riesgos. La solución consiste en utilizar el modo de transmisión de Chromium (ReturnAsStream) junto con un buffer de lectura de, por ejemplo, 1 MB. A medida que Chrome renderiza, Node.js va extrayendo fragmentos y los sube directamente a un almacenamiento S3 mediante carga multiparte. De esta forma, el pico de memoria por documento se mantiene constante (~20 MB) independientemente del tamaño final. No hay acumulación; si S3 se ralentiza, el flujo retropropaga la presión, evitando colapsos. Este patrón de streaming con backpressure es esencial para garantizar estabilidad en producción real, más allá de las demos controladas.

Desde el punto de vista de la seguridad, los datos sensibles (nombres, direcciones, importes) deben protegerse en reposo y en tránsito. Una práctica recomendada es cifrar las cargas útiles con AES-256-GCM antes de almacenarlas temporalmente, usando claves derivadas con HKDF a partir de un secreto maestro y un salt aleatorio por cada documento. Así, incluso si la base de datos se viera comprometida, no existiría una tabla de claves que exponer. Además, los artefactos generados deben tener una vida útil corta: previsualizaciones que se eliminan en 24 horas y documentos finales en pocos días. La mejor mitigación de una brecha es que los datos ya no existan. Complementariamente, los webhooks de notificación deben estar firmados con HMAC-SHA256 y validarse con comparación en tiempo constante para evitar ataques de temporización.

Desde una perspectiva empresarial, surge la disyuntiva clásica: construir o comprar. Si la generación de PDF no es el núcleo de tu negocio, sino un medio para emitir facturas o informes, una API gestionada que cobre céntimos por documento puede ser la opción más rentable. Te ahorras el mantenimiento de Chromium, las actualizaciones de seguridad, la gestión del almacenamiento y la operación continua. Sin embargo, cuando los volúmenes son tan altos que el coste por documento se vuelve significativo, o cuando la legislación impide que los datos salgan de tu infraestructura, o cuando necesitas capacidades de renderizado muy específicas (fuentes personalizadas, scripts complejos), entonces construir tu propia API con Postgres y Chromium se convierte en la decisión acertada. Ese es el momento de aplicar este blueprint.

En este contexto, contar con un socio tecnológico que entienda las sutilezas de la arquitectura cloud y la optimización de costes es clave. Servicios cloud AWS y Azure ofrecen la elasticidad necesaria para manejar picos de demanda sin sobredimensionar, pero requieren un diseño cuidadoso para no multiplicar la complejidad. Sistemas como PostgreSQL gestionan tanto la base de datos principal como la cola de trabajos, mientras que S3 (o equivalentes) proporcionan almacenamiento duradero para los PDFs generados. La integración con herramientas de inteligencia artificial puede añadir valor: por ejemplo, clasificar automáticamente documentos, extraer datos mediante OCR o personalizar plantillas basándose en perfiles de usuario. Asimismo, la ciberseguridad debe estar presente desde el diseño, protegiendo cada capa del pipeline.

La implementación práctica suele combinarse con frameworks modernos como SvelteKit o Hono para la API, y pg-boss como cola embebida en Postgres. No se necesita un cluster de Kubernetes; bastan unas pocas réplicas de trabajadores que comparten un pool de conexiones a Chromium. La monitorización se simplifica: una sola base de datos, un solo sistema de logs. Para equipos que desarrollan software a medida, este tipo de arquitectura permite iterar rápido, desplegar en entornos reducidos y escalar horizontalmente cuando el negocio lo requiera, sin arrastrar deuda técnica innecesaria.

En cuanto al rendimiento, las pruebas de carga muestran que una máquina virtual compartida (por ejemplo, 9 de 24 hilos) puede ingerir del orden de 5.900 documentos por segundo en la cola, mientras que el renderizado se estabiliza en unos 63 PDFs por segundo, limitado por el pool de Chromium. Ese desfase de 90 veces es intencional: la cola absorbe la ráfaga y los trabajadores procesan a su ritmo natural. La latencia P95 bajo saturación puede rondar los 5 segundos, perfectamente aceptable para procesos batch. La clave está en no acoplar la tasa de aceptación con la tasa de procesamiento, un error típico en diseños más acoplados.

Por último, la decisión de construir una API de PDF interna debe alinearse con la estrategia global de la empresa. Si ya se cuenta con un equipo que domina Postgres y Node.js, añadir Chromium y S3 no supone un salto enorme. Pero si el core del negocio es otro, externalizar la generación de PDF a un servicio especializado libera recursos para innovar en el producto principal. En cualquier caso, entender los principios de este blueprint —simplicidad, streaming, colas embebidas, seguridad por diseño— proporciona una base sólida para evaluar cualquier solución, ya sea propia o de terceros.

En Q2BSTUDIO, ayudamos a empresas a diseñar e implementar este tipo de arquitecturas, combinando automatización de procesos con buenas prácticas de cloud, inteligencia artificial y ciberseguridad. Desde la creación de aplicaciones a medida hasta la integración de servicios inteligencia de negocio como Power BI, pasando por la implementación de agentes IA que optimicen la generación de documentos, nuestro enfoque es pragmático: menos dependencias, más control, y un roadmap claro hacia la escalabilidad. Porque al final, el mejor sistema es el que puedes operar con un equipo pequeño, mantener con confianza y escalar cuando llegue el momento.