Quickstart

Tres formas de levantarlo: local, local con PDF (LibreOffice instalado) y Docker. Todas exponen el API en http://localhost:3000.

1. Local (rápido, sólo .docx)

cd converter-api
cp .env.example .env
# Edita API_KEY en .env (genera una con: node -e "console.log(require('crypto').randomBytes(24).toString('hex'))")

npm install
npm run dev

El servidor escucha en :3000. Verifica:

curl -s http://localhost:3000/health

Sin LibreOffice instalado, /health responde { status: "degraded", libreoffice: { available: false } }. El flujo .docx funciona; el flujo PDF devolverá 503 LIBREOFFICE_UNAVAILABLE.

2. Local con PDF

# macOS
brew install --cask libreoffice

# Debian / Ubuntu
sudo apt-get install -y libreoffice fonts-dejavu fonts-liberation

# Reinicia el server
npm run dev

3. Docker (incluye LibreOffice + fuentes)

docker compose up --build

La imagen base es node:20-slim con libreoffice, fonts-dejavu, fonts-liberation y fontconfig. Volúmenes montados:

./templates → /app/templates
./images → /app/images

Variables de entorno

Todas viven en .env (no commiteado). Sólo API_KEY es obligatoria.

Variable	Default	Notas
`PORT`	3000
`NODE_ENV`	development
`API_KEY`	—	requerida
`TEMPLATES_DIR`	./templates
`IMAGES_DIR`	./images	volumen externo
`TMP_DIR`	`os.tmpdir()/converter-api`
`MAX_UPLOAD_MB`	10	límite multer
`MAX_IMAGE_MB`	5	imagen por tag
`LO_CONCURRENCY`	1	conversiones simultáneas
`LO_TIMEOUT_MS`	60000
`HTTP_FETCH_TIMEOUT_MS`	10000	timeout fetch imagen
`LOG_LEVEL`	info	pino

Primer render — flujo completo

Sube una plantilla, renderiza, descarga.

(1) Subir plantilla

source .env
curl -X POST http://localhost:3000/templates \
  -H "x-api-key: $API_KEY" \
  -F slug=factura-demo \
  -F file=@tests/fixtures/factura.docx \
  -F schema=@tests/fixtures/factura.schema.json

(2) Renderizar

curl -X POST http://localhost:3000/render \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -o factura.docx \
  -d '{
    "slug": "factura-demo",
    "data": {
      "folio": "F-001",
      "cliente": { "nombre": "Acme S.A. de C.V." },
      "items": [
        { "descripcion": "Servicio mensual", "cantidad": 12 },
        { "descripcion": "Soporte premium",  "cantidad": 1  }
      ],
      "descuento": 10
    }
  }'

(3) Borrar (cleanup opcional)

curl -X DELETE http://localhost:3000/templates/factura-demo \
  -H "x-api-key: $API_KEY"

Atajo

Hay un script scripts/smoke.sh en el repo que ejecuta este flujo completo (incluyendo casos negativos). Útil para verificar que el deployment responde como esperas.

Postman

En docs/postman/ hay una colección con todos los endpoints, variables (baseUrl, apiKey, slug) y tests automatizados. Importa los dos archivos JSON, edita el environment con tu API key, y corre las requests en orden.