Formati dei dati

Qui trovi la struttura in cui devono arrivare i dati. PDFgine non stampa il valore inviato così com'è: applica il formattatore dichiarato dal modello, nella lingua del documento.

In una frase: i dati arrivano grezzi, PDFgine li formatta. Se invii un valore già formattato, il documento risulterà corretto in una lingua e sbagliato nell'altra.

Un formattatore si dichiara in tre punti: nel campo "format" di una colonna di tabella e di una riga di riepilogo, in "dataRules.formatter" su un elemento che stampa un singolo valore e con le funzioni format_date e format_money nel testo che unisce più campi.

{
  "issueDate": "2026-09-06",
  "currency": "USD",
  "lineItems": [
    { "name": "Sito web aziendale", "quantity": 1, "unitPrice": 24000, "total": 24000 }
  ]
}

// Nel modello:
// colonna della tabella:   "format": { "kind": "currency", "currency": "USD", "decimals": 2 }
// colonna della data:    "format": { "kind": "date", "dateStyle": "short" }
// elemento di testo:   "{{ referenceNo }} · {{ format_date issueDate }}"

Anche IBAN, numeri di telefono e fiscali arrivano in forma canonica: IBAN senza spazi, telefono in E.164 (+442071838750). Il raggruppamento è un formato di presentazione e non fa parte dei dati.

Il nome con cui arriva il documento

Un documento scaricato si chiama "{document type} - {counterparty} - {reference no}". Le tre parti provengono dai dati inviati: document.title, customer e referenceNo. Le parti mancanti vengono omesse e, se nessuna consente di ottenere un nome utilizzabile, il documento usa la propria identità, ad esempio quote-doc_94812af2.pdf.

Content-Disposition: attachment;
  filename="Quote - Müller og Søn ApS - QUO-2026-0042.pdf";
  filename*=UTF-8''Quote%20-%20M%C3%BCller%20og%20S%C3%B8n%20ApS%20-%20QUO-2026-0042.pdf

Il nome viene scritto due volte nella stessa intestazione. Il campo esteso conserva la lingua del documento; quello classico contiene una versione ASCII leggibile per i client che non leggono il campo esteso. I caratteri non accettati dai file system (barra, barra inversa, due punti, asterisco, punto interrogativo, virgolette, minore, maggiore, barra verticale) vengono rimossi insieme ai caratteri di controllo, e il nome viene limitato per funzionare su ogni file system.

Immagini

Un elemento immagine del modello può essere associato a un campo dati: la sorgente arriva con la richiesta. Sono accettate due forme: l'ID di una risorsa caricata (ast_…, per loghi, timbri e firme ripetuti; si carica una volta e viaggia solo l'ID) e un'immagine inline (data:image/png;base64,…, per immagini singole). Se il campo è assente o vuoto, si usa l'immagine del modello; se un valore presente non è utilizzabile, la richiesta viene rifiutata con 422 e la risposta indica il campo dati.

{
  "templateCode": "invoice",
  "format": "pdf",
  "data": {
    "logo": "ast_9f1c7b1f0f6b4f5f9f0a0d1e2c3b4a59",
    "signature": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Limiti: un'immagine inline deve essere PNG, JPEG o WebP, massimo 2 MB per immagine e 6 MB per tutte le immagini di un documento. Una risorsa caricata può arrivare a 10 MB. Per immagini temporanee passa expiresInMinutes al caricamento (da 1 minuto a 7 giorni): una risorsa scaduta si elimina da sola.

Risorse

Loghi, firme e font vengono caricati una volta e richiamati tramite ID. La pagina dedicata illustra il caricamento, i limiti e i permessi dei font.

Gli errori più comuni

• Un valore già formattato viene stampato come arriva. "1.234,56" si legge correttamente in una lingua e male in un'altra, e nessun formattatore può correggerlo dopo.
• Una data deve essere ISO 8601. Un formato locale arriva come testo: non viene formattato, ordinato né tradotto.
• La valuta non va inclusa nell'importo. Invia il numero e lascia che il formattatore della colonna aggiunga il codice ISO.
• Una percentuale si invia su cento: 18 per 18%. Inviare 0.18 stampa zero virgola diciotto percento.
• Una condizione legge un booleano JSON. La stringa "false" è un testo non vuoto e conta come presente.