Borradores, publicación y versiones

Guardar no es publicar

Guardar actualiza el borrador de la plantilla. Publicar selecciona una versión para producción. Una plantilla puede tener una versión publicada mientras trabajas en un borrador más reciente; no supongas que los cambios del borrador ya están publicados.

Antes de publicar

Prueba la vista previa con datos de ejemplo y datos reales largos y verifica los formatos de salida necesarios. Compara las versiones activa y publicada en Historial. Publica cuando esté listo el contenido que quieras usar en producción.

Restaurar desde el historial

Restaurar una versión histórica guarda ese contenido como nueva versión activa; no borra el historial anterior. Comprueba el contenido tras restaurar. Publica por separado si también quieres reemplazar la versión publicada.

Leer, restaurar y publicar una versión

Cada guardado manual crea una versión nueva y nunca se sobrescribe nada. Restaurar una versión anterior no elimina las posteriores: guarda la definición antigua como una versión nueva para mantener el historial completo.

# Lista de versiones - la más reciente primero
curl -s https://api.pdfgine.com/api/v1/templates/invoice/history \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# La definición de una versión
curl -s https://api.pdfgine.com/api/v1/templates/invoice/history/3 \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# Volver a esa versión - se guarda como una versión nueva y se conserva la antigua
curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/history/3/restore \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# Publicar el borrador
curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/publish \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

{
  "type": "https://pdfgine.dev/problems/template-conflict",
  "title": "Conflicto de plantilla",
  "status": 409,
  "detail": "Otra operación ha modificado la plantilla. Carga la versión actual y vuelve a intentarlo.",
  "templateCode": "invoice",
  "currentVersion": 19,
  "currentDraftRevision": 0
}

Una escritura con un expectedVersion desactualizado se rechaza en lugar de fusionarse. El cuerpo del 409 indica la plantilla, su versión actual y la revisión del borrador; lee la definición actual, vuelve a aplicar el cambio y guarda de nuevo.

Conflictos y códigos de conexión

Guardar desde una versión antigua puede provocar un conflicto si otra sesión ha modificado la misma plantilla. Revisa el estado y el historial en lugar de sobrescribir a ciegas. El código de conexión identifica la plantilla en las solicitudes API. Si cambia, actualiza también las integraciones que lo usen.

Los errores más habituales

• Guardar no es publicar. Un borrador puede estar perfecto durante días mientras la producción sigue imprimiendo la última versión publicada.
• Restaurar no elimina nada. Guarda la definición antigua como una versión nueva, conservando el historial y aumentando el número de versión.
• Un 409 repetido con el mismo expectedVersion vuelve a rechazarse. Lee la versión actual, aplica el cambio sobre ella y escribe de nuevo.
• Una renderización con purpose editor-test usa el borrador; production usa la versión publicada. Dos renderizaciones aparentemente iguales pueden proceder de diseños diferentes.
• El endpoint del historial está paginado. Sin limit obtienes la página más reciente y una cabecera Link; tratar esa página como todo el historial oculta las revisiones antiguas.