Schema JSON del modello

Struttura di una definizione

Una definizione di modello è un oggetto con due parti: page definisce il foglio ed elements è l'elenco ordinato degli elementi disegnati su di esso.

{
  "page": {
    "size": "A4",
    "orientation": "portrait",
    "margin": { "top": 48, "right": 48, "bottom": 48, "left": 48 }
  },
  "elements": [
    {
      "id": "invoice-title",
      "type": "heading",
      "placementMode": "flow",
      "content": { "text": "Invoice" },
      "layout": { "width": 100, "widthUnit": "percent", "height": 40 },
      "style": { "fontSize": 24, "textStyle": "bold" }
    }
  ]
}

Formati pagina: A4 · A3 · Letter. L'orientamento è portrait o landscape e i margini sono in pixel CSS, 96 per pollice.

Quale elemento accetta quale campo

Ogni elemento contiene id, type, placementMode. Tutto il resto dipende dal tipo e la tabella seguente viene generata dalle stesse regole usate dal validatore: non può restare indietro rispetto al prodotto.

Un campo non presente nella riga del proprio tipo causa un errore di convalida anziché essere ignorato. Scartarlo in silenzio sarebbe peggio: il documento uscirebbe incompleto mentre la richiesta sembrerebbe riuscita.

placementMode

Come un elemento trova la propria posizione sul foglio. La modalità decide anche se layout.x e layout.y vengono letti.

• flow — disposti uno dopo l'altro lungo la pagina; x e y vengono ignorati e l'elemento cresce con il contenuto
• free — posizionato in layout.x e layout.y, esattamente dove lo collochi
• band — ripetuto su ogni pagina nella fascia indicata dall'elemento, ad esempio intestazione o piè di pagina

L'elemento dataset

Un dataset stampa una raccolta che non è una tabella: un elenco di visite, fotografie o firme, disegnato secondo il layout del modello anziché in colonne.

{
  "id": "maintenance-visits",
  "type": "dataset",
  "placementMode": "flow",
  "binding": "visits",
  "layout": { "width": 100, "widthUnit": "percent", "height": 160 },
  "style": { "fontSize": 11 },
  "dataRules": { "required": true }
}

binding indica l'array nei dati, proprio come in una tabella. Ciò che viene disegnato per ogni elemento dipende da layout e stile, quindi la stessa raccolta può essere una tabella in un modello e un dataset in un altro.

Un dataset non ha un campo content. Riceve dati solo tramite binding: il testo che si trovava in content non arrivava mai all'output, quindi il campo è stato rimosso anziché restare uno spazio di scrittura senza effetto.

Controllare i dati prima della generazione

L'endpoint di convalida risponde alla stessa domanda della generazione senza consumare quota: questi dati soddisfano i requisiti del modello?

curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/validate-data \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "referenceNo": "DOC-2026-0042", "currency": "USD" } }'

Gli errori più comuni

• Un campo estraneo al tipo di elemento causa un errore di convalida anziché essere ignorato. È voluto: scartarlo in silenzio produce un documento incompleto e nessuno cerca ciò che manca.
• Nel posizionamento flow, layout.x e layout.y non vengono letti. Impostarli e chiedersi perché nulla si sposti è la domanda più comune sullo schema.
• Un dataset non ha un campo content: riceve dati solo da binding. Il testo inserito in content non raggiunge mai l'output.
• Margini e dimensioni sono pixel CSS, 96 per pollice, non millimetri. Un 20 inteso come millimetri risulta tre volte troppo piccolo.
• Generare per verificare se i dati vanno bene costa una pagina. L'endpoint di convalida risponde alla stessa domanda senza costi.