Elenca modelli

Cos'è un modello

Un modello è un design di documento salvato con un codice scelto da te. Ha due vite contemporaneamente: una bozza che continui a modificare e una versione pubblicata usata per la produzione. Salvare non pubblica, quindi una modifica incompleta non può raggiungere i clienti.

Restituisce i modelli dello spazio di lavoro con i numeri delle versioni pubblicate. Per generare usi il codice del modello.

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

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

Formato del numero di pagina

Il contenuto di un elemento numero di pagina è un formato: {{ page }} diventa la pagina attuale e {{ pages }} il totale. Scrivendo “{{ page }} / {{ pages }}” il documento stampa “3 / 12”, con contatori nel PDF e codici campo PAGE/NUMPAGES in Word, entrambi aggiornati automaticamente quando si aggiungono pagine. Se il contenuto non contiene segnaposto, viene ignorato e si stampa solo il numero di pagina.

Salvare una versione

Il salvataggio include la versione che ritieni di modificare. Se qualcun altro ha salvato nel frattempo, la risposta è 409 e indica la versione attuale, senza sovrascrivere nulla in silenzio.

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": "Fattura aziendale",
        "saveMode": "manual",
        "expectedVersion": 5,
        "changeReason": "Logo spostato al margine destro.",
        "definition": {
          "page": { "size": "A4", "orientation": "portrait" },
          "elements": [
            { "type": "text", "text": "Fattura aziendale", "fontSize": 24 }
          ]
        }
      }'

HTTP/1.1 409 Conflict

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

expectedVersion è facoltativo ma consigliato: senza di esso prevale l'ultima scrittura e la modifica precedente scompare senza traccia.

Gli errori più comuni

• 409 non è un errore da ritentare alla cieca. Leggi currentVersion, prendi la definizione più recente, applicaci la modifica e salva di nuovo.
• Salvare non equivale a pubblicare. La produzione continua a usare l'ultima versione pubblicata finché non pubblichi la bozza.
• L'elenco restituisce al massimo 200 modelli. Se ce ne sono altri, la risposta contiene un'intestazione Link con rel="next": seguila anziché presumere che la prima pagina sia l'intera libreria.
• La lettura richiede templates:read e il salvataggio templates:write. Una chiave di sola lettura risponde 403 al salvataggio, non 401.
• Il codice permette a tutte le altre chiamate di trovare il modello. Puoi cambiarne liberamente il nome; cambiare codice significa creare un nuovo modello.