Templates (CRUD)

Todas las plantillas viven en TEMPLATES_DIR identificadas por un slug único. El slug debe matchear la regex /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/ — sólo minúsculas, dígitos y guiones (no inicial/final), entre 1 y 64 caracteres.

POST /templates

POST/templatesrequiere x-api-key

Sube una plantilla nueva. Devuelve 409 si el slug ya existe.

Request

multipart/form-data con tres campos:

Campo	Tipo	Requerido	Descripción
`slug`	text	sí	Identificador único.
`file`	file (.docx)	sí	Plantilla. Máx `MAX_UPLOAD_MB`.
`schema`	file (.json)	no	JSON Schema para validar futuros renders.

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

Response 201

{
  "slug": "factura-cliente-2026",
  "sizeBytes": 8573,
  "updatedAt": "2026-04-29T00:36:43.820Z",
  "hasSchema": true
}

Errores

400 INVALID_INPUT — slug con formato inválido o falta el campo file.
409 TEMPLATE_CONFLICT — el slug ya existe (usa PUT para reemplazar).
413 PAYLOAD_TOO_LARGE — el archivo excede MAX_UPLOAD_MB.

GET /templates

GET/templatesrequiere x-api-key

Lista plantillas registradas.

curl -H "x-api-key: $API_KEY" http://localhost:3000/templates

{
  "templates": [
    {
      "slug": "factura-cliente-2026",
      "sizeBytes": 8573,
      "updatedAt": "2026-04-29T00:36:43.820Z",
      "hasSchema": true
    }
  ]
}

GET /templates/:slug

GET/templates/:slugrequiere x-api-key

Descarga el .docx original.

curl -H "x-api-key: $API_KEY" \
  -o factura.docx \
  http://localhost:3000/templates/factura-cliente-2026

Respuesta: stream binario con Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document y Content-Disposition: attachment; filename="<slug>.docx".

Errores

404 TEMPLATE_NOT_FOUND — el slug no existe.

PUT /templates/:slug

PUT/templates/:slugrequiere x-api-key

Reemplaza .docx y/o schema de una plantilla existente.

Cuerpo multipart/form-data. Cada campo es independiente: si omites file el .docx se conserva; si omites schema el schema previo se conserva.

Sólo reemplazar el .docx

curl -X PUT http://localhost:3000/templates/factura-cliente-2026 \
  -H "x-api-key: $API_KEY" \
  -F file=@./factura-v2.docx

Reemplazar .docx y schema

curl -X PUT http://localhost:3000/templates/factura-cliente-2026 \
  -H "x-api-key: $API_KEY" \
  -F file=@./factura-v2.docx \
  -F schema=@./factura-v2.schema.json

Quitar el schema sin tocar el .docx

curl -X PUT http://localhost:3000/templates/factura-cliente-2026 \
  -H "x-api-key: $API_KEY" \
  -F schema_clear=true

Sin historial

El PUT sobreescribe sin guardar versión anterior. Si necesitas auditoría, snapshot manualmente antes de actualizar.

DELETE /templates/:slug

DELETE/templates/:slugrequiere x-api-key

Elimina .docx y schema.

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

Respuesta 204 No Content en éxito. 404 si el slug no existía.