Listar plantillas

Qué es una plantilla

Una plantilla es un diseño de documento guardado con un código que eliges. Tiene dos estados a la vez: un borrador que sigues editando y una versión publicada que usa la generación de producción. Guardar no publica, por lo que un cambio incompleto no puede llegar a tus clientes.

Devuelve las plantillas de tu espacio de trabajo con los números de sus versiones publicadas. El código de la plantilla se usa al renderizar.

curl https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

[
  {
    "templateId": "tpl_eca4c9985ad74913902f0469469936a1",
    "code": "invoice",
    "name": "Factura corporativa",
    "version": 5,
    "publishedVersion": 1,
    "publishedAt": "2026-08-23T08:23:21+00:00"
  }
]

Formato del número de página

El contenido de un elemento de número de página es un formato: {{ page }} se convierte en la página actual y {{ pages }} en el total. Escribe «{{ page }} / {{ pages }}» y el documento imprime «3 / 12», con contadores en el PDF y códigos de campo PAGE/NUMPAGES en Word para actualizarse solos al añadir páginas. Si el contenido no incluye marcadores, se ignora y solo se imprime el número de página.

Guardar una versión

El guardado incluye la versión que crees estar editando. Si otra persona ha guardado mientras tanto, la respuesta es 409 e indica la versión actual, para evitar sobrescrituras silenciosas.

curl -X POST https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "code": "invoice",
        "name": "Factura corporativa",
        "saveMode": "manual",
        "expectedVersion": 5,
        "changeReason": "Logotipo movido al margen derecho.",
        "definition": {
          "page": { "size": "A4", "orientation": "portrait" },
          "elements": [
            { "type": "text", "text": "Factura corporativa", "fontSize": 24 }
          ]
        }
      }'

HTTP/1.1 409 Conflict

{
  "type": "https://pdfgine.dev/problems/template-conflict",
  "templateCode": "invoice",
  "currentVersion": 6,
  "currentDraftRevision": 0
}

expectedVersion es opcional, pero recomendable: sin él, gana la última escritura y el cambio anterior desaparece sin dejar rastro.

Los errores más habituales

• 409 no es un error que debas reintentar a ciegas. Lee currentVersion, obtén la definición más reciente, aplica tu cambio sobre ella y guarda de nuevo.
• Guardar no es publicar. La generación de producción sigue usando la última versión publicada hasta que publiques el borrador.
• El listado devuelve como máximo 200 plantillas. Si hay más, la respuesta incluye una cabecera Link con rel="next"; síguela en lugar de suponer que la primera página contiene toda la biblioteca.
• La lectura requiere templates:read y el guardado templates:write. Una clave de solo lectura recibe un 403 al guardar, no un 401.
• Todas las demás llamadas encuentran la plantilla por su código. Puedes cambiar su nombre libremente; cambiar el código implica crear otra plantilla.