Vai al contenuto
Menu della documentazione

Parametri

Gli input tipizzati di un template, collegati alle variabili SQL, passati per nome tramite API e validati prima della generazione.

I parametri sono gli input di un template: l'id della fattura da stampare, un intervallo di date, una lingua, un'opzione. La tua applicazione li passa per nome quando genera il documento; i dataset li usano come bind variable SQL e il layout può stamparli o usarli nelle condizioni.

Che cos'è un parametro

Definisci i parametri nel pannello Parametri del Designer:

nometestoobbligatorio
Lettere, cifre e _, senza iniziare con una cifra, unico nel template. È il nome che la tua applicazione invia (DOCUMENT_ID).
tipoelenco
string, integer, decimal, date, dateTime o boolean (vedi sotto). Predefinito string.
obbligatoriosì/no
Un parametro obbligatorio senza valore e senza predefinito fa fallire la generazione.
predefinitovalore
Usato quando chi chiama non invia un valore.
valore di provavalore
Usato solo nel Designer: prove dei dataset, anteprime e prove di generazione.
descrizionetesto
Mostrata nell'API explorer e restituita da GET /v1/templates/{code}.
logsì/no
Registra il valore nel log delle esecuzioni (attivo come predefinito). Disattivalo per i valori riservati.

Una bind variable senza parametro corrispondente può diventarlo con Crea parametro nell'editor dei dataset: viene aggiunto come obbligatorio, con un tipo dedotto dal nome.

Tipi e valori

stringtesto
Qualsiasi valore scalare, usato come testo.
integernumero intero
Un intero JSON o un testo con un intero: 18425 oppure "18425".
decimalnumero
Un numero JSON o un testo con il punto come separatore decimale: 12.5 oppure "12.5".
datedata
Testo ISO: "2026-10-31".
dateTimedata e ora
Testo ISO: "2026-10-31T14:30", con i secondi, o con uno spazio al posto di T; con Z o un offset l'ora resta quella scritta.
booleansì/no
true / false, oppure 1 / 0 (anche come testo).

Un testo vuoto vale "nessun valore" per tutti i tipi tranne string. Predefiniti e valori di prova si scrivono nello stesso formato invariante (date ISO, il punto per i decimali, true/false); un predefinito non valido viene segnalato al salvataggio.

I parametri nell'SQL

In un dataset scrivi il parametro come bind variable, :NOME. Prynt passa il valore con il suo tipo; non viene mai incollato nel testo SQL, quindi un valore non può cambiare la query (niente SQL injection) e il database può riusare il piano di esecuzione.

Dataset con parametri
SELECT r.RIGA, r.ARTICOLO, r.QUANTITA  FROM DDT_RIGHE r WHERE r.DDT_ID = :DOCUMENT_ID   AND r.DATA >= :FROM_DATE   AND r.DATA <  :TO_DATE + 1          -- tutto l'ultimo giorno   AND (:CUSTOMER IS NULL OR r.CLIENTE = :CUSTOMER)
  • Un valore nullo viene passato come NULL tipizzato: i filtri facoltativi si scrivono (:P IS NULL OR colonna = :P).
  • Un parametro date arriva come data a mezzanotte: per includere tutto l'ultimo giorno di un intervallo su colonne con data e ora, confronta con < :TO_DATE + 1.
  • Su Oracle un booleano arriva come numero 1 o 0, e un testo vuoto è NULL. Vedi Oracle.
  • Non si costruisce mai SQL con i valori dei parametri: per costruzione non c'è modo di farlo.

I parametri nel layout

Nelle espressioni un parametro è Params.NOME: lo stampi in un testo ({{Params.DOCUMENT_ID}}), lo usi in una condizione (Visibile se Params.SHOW_PRICES) o nel numero di copie di un'etichetta (Params.COPIE).

Passare i parametri tramite API

Invia i valori nell'oggetto parameters di POST https://api.prynt.it/api/v1/render, per nome, con i tipi JSON visti sopra:

Corpo della richiesta
{  "template": "DELIVERY_NOTE",  "parameters": {    "DOCUMENT_ID": 18425,    "FROM_DATE": "2026-10-01",    "TO_DATE": "2026-10-31",    "CUSTOMER": null,    "SHOW_PRICES": true  },  "context": { "company": "01", "user": "erp-batch", "language": "en" }}
  • I nomi non distinguono maiuscole e minuscole: document_id e DOCUMENT_ID sono lo stesso parametro.
  • I parametri che il template non dichiara vengono ignorati.
  • GET /v1/templates/{code} restituisce i parametri della versione pubblicata con i loro tipi, e un JSON Schema dell'oggetto parameters con cui validare. L'API explorer scrive la richiesta per te con i nomi veri.

Validazione ed errori

Prynt converte e controlla ogni valore rispetto al tipo dichiarato prima di eseguire qualsiasi query. Un parametro obbligatorio mancante (senza predefinito) o un valore non convertibile risponde 400 con errorCode PARAMETER_INVALID, il nome del parametro e il motivo in reason: missing o invalid.

400 PARAMETER_INVALID
HTTP/1.1 400 Bad RequestContent-Type: application/problem+json {  "title": "Invalid parameter",  "status": 400,  "detail": "…",  "errorCode": "PARAMETER_INVALID",  "parameter": "DOCUMENT_ID",  "reason": "missing",  "correlationId": "4bf92f3577b34da6a3ce929d0e0e4736"}

Correggi la richiesta, non il template, e non ripetere la stessa chiamata. Nel Designer l'anteprima mostra lo stesso errore accanto al campo del parametro.

Valori di sistema e contesto

Oltre ai parametri, un template può usare i valori di sistema: $DITTA (la ditta), $USER, $LANGUAGE, $DATE e $NOW nelle espressioni, :DITTA, :USER, :LANGUAGE, :DATE, :NOW come bind variable. Ditta, utente e lingua arrivano dal context facoltativo della richiesta di generazione (predefiniti: la ditta impostata nelle impostazioni del workspace, il nome della chiave API e l'italiano); DATE e NOW sono data e ora del server. La lingua decide anche il formato di numeri e date e le traduzioni del template.

Un parametro nasconde un valore di sistema

Un parametro con il nome di un valore di sistema (DITTA, USER…) ne prende il posto nelle bind variable senza un collegamento esplicito. Scegli nomi diversi, a meno che non sia proprio ciò che vuoi.

Valori riservati

L'opzione Log

Come predefinito i valori dei parametri vengono registrati con ogni esecuzione, per riprodurre un problema in seguito. Disattiva Log per i valori che non devono essere conservati (un codice fiscale, un documento d'identità): restano allora fuori dal log delle esecuzioni, dal nome del file e dai messaggi d'errore registrati.