Bozze, pubblicazione e versioni

Salvare non equivale a pubblicare

Il salvataggio aggiorna la bozza su cui lavori. La pubblicazione sceglie una versione per la produzione. Un modello può avere una versione pubblicata mentre lavori a una bozza più recente: non presumere che le modifiche alla bozza siano già pubblicate.

Prima di pubblicare

Controlla l'anteprima con dati di esempio e dati realistici lunghi, verificando i formati richiesti. Confronta versione attiva e pubblicata nella Cronologia. Pubblica quando il contenuto destinato alla produzione è pronto.

Ripristinare dalla cronologia

Il ripristino di una versione storica salva quel contenuto come nuova versione attiva, senza cancellare la cronologia precedente. Ricontrolla il contenuto dopo il ripristino. Pubblica separatamente se vuoi sostituire anche la versione pubblicata.

Leggere, ripristinare e pubblicare una versione

Ogni salvataggio manuale crea una nuova versione e nulla viene sovrascritto. Il ripristino di una versione precedente non elimina quelle successive: scrive la vecchia definizione come nuova versione, mantenendo completa la cronologia.

# Elenco delle versioni - dalla più recente
curl -s https://api.pdfgine.com/api/v1/templates/invoice/history \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# La definizione di una versione
curl -s https://api.pdfgine.com/api/v1/templates/invoice/history/3 \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# Torna a quella versione - scritta come nuova versione, conservando la precedente
curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/history/3/restore \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

# Pubblica la bozza
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": "Conflitto del modello",
  "status": 409,
  "detail": "Il modello è stato modificato da un'altra operazione. Carica la versione attuale e riprova.",
  "templateCode": "invoice",
  "currentVersion": 19,
  "currentDraftRevision": 0
}

Una scrittura con expectedVersion non aggiornata viene rifiutata anziché unita. Il corpo della risposta 409 indica il modello, la versione attuale e la revisione della bozza: leggi la definizione attuale, riapplica la modifica e scrivi di nuovo.

Conflitti e codici di collegamento

Salvare da una versione non aggiornata può creare conflitti se un'altra sessione ha modificato lo stesso modello. Controlla stato attuale e cronologia anziché sovrascrivere alla cieca. Il codice di collegamento identifica il modello nelle richieste API; se cambia, aggiorna anche le integrazioni che lo usano.

Gli errori più comuni

• Salvare non equivale a pubblicare. Una bozza può essere perfetta da giorni mentre la produzione continua a usare l'ultima versione pubblicata.
• Il ripristino non elimina nulla. Scrive la vecchia definizione come nuova versione, mantenendo la cronologia e facendo crescere il numero di versione.
• Un 409 ripetuto con la stessa expectedVersion viene rifiutato di nuovo. Leggi la versione attuale, applicaci la modifica e poi scrivi.
• Una generazione con purpose editor-test usa la bozza; production usa la versione pubblicata. Due generazioni apparentemente identiche possono derivare da due design diversi.
• L'endpoint della cronologia è paginato. Senza limit ottieni la pagina più recente e un'intestazione Link; considerarla l'intera cronologia nasconde le revisioni precedenti.