docgen-platform

Servicio HTTP que genera documentos Word (.docx) o PDF a partir de plantillas .docx con sintaxis docxtemplater. Recibe un slug de plantilla y un JSON de datos; devuelve el documento renderizado.

Para qué sirve
Sustituir generación manual de facturas, contratos, constancias, reportes y cualquier documento estructurado que parta de una plantilla Word con valores dinámicos. Optimizado para que los equipos de negocio mantengan las plantillas sin tocar código.

Cómo funciona

  1. Subes una plantilla .docx a través del API con un slug único (ej. factura-cliente-2026).
  2. Opcionalmente adjuntas un .json JSON Schema describiendo qué datos espera la plantilla. Si lo provees, los requests al render son validados antes de generar el documento.
  3. Llamas a POST /render con el slug y un payload de datos. Recibes el documento generado como stream binario.

Stack

  • Node 20 · Express 4
  • docxtemplater + pizzip + image module (renderer)
  • libreoffice-convert (conversión a PDF)
  • zod (validación de payloads del API) · ajv (validación de datos vs schema de plantilla)
  • pino (logs estructurados con request-id)
  • multer (upload de plantillas)

Decisiones clave

  • Mono-tenant. Una sola API_KEY compartida; se valida con crypto.timingSafeEqual.
  • Slugs URL-safe. El cliente provee el slug; debe matchear /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/. El servidor rechaza colisiones con 409.
  • Storage en filesystem. Sin DB. Una plantilla = un archivo <slug>.docx y opcionalmente <slug>.schema.json en TEMPLATES_DIR.
  • Imágenes en celda 1×1. Las etiquetas {%logo} deben vivir en una celda de tabla 1×1. El ancho de la celda determina el ancho de la imagen renderizada.
  • SSRF guard en URLs HTTP de imágenes (bloqueo de IPs privadas, loopback, link-local).

Estructura del API

Endpoints en /health, /templates y /render. Todos excepto GET /health requieren el header x-api-key.

Empieza por Quickstart si vienes a probar, o por la referencia del API si vienes a integrar.