Placeholder

I placeholder sono campi compilabili posizionati sui documenti PDF che i firmatari possono (o devono) compilare durante il processo di firma. Permettono di raccogliere informazioni aggiuntive direttamente sul documento: testo libero, date, checkbox, menu a tendina, allegati e molto altro.

Come Funzionano

I placeholder vengono definiti nella creazione della pratica (POST /api/v2/files/send) a due livelli:

• A livello di pratica: nel campo placeholders del body principale (comuni a tutti i firmatari)
• A livello di firmatario: nel campo signers[].placeholders (assegnati a un firmatario specifico)

{
  "documents": [{ "filename": "contratto.pdf", "base64content": "..." }],
  "name": "Contratto con campi compilabili",
  "signers": [
    {
      "email": "[email protected]",
      "action": "S",
      "placeholders": [
        {
          "type": "T",
          "code": "citta",
          "document": 0,
          "page": 1,
          "positionX": 0.3,
          "positionY": 0.5,
          "width": 0.2,
          "height": 0.03,
          "required": true
        }
      ]
    }
  ]
}

---

Tipi di Placeholder

Testo e Dati Personali

Codice	Tipo	Descrizione
T	Testo libero	Campo di testo compilabile dal firmatario. Supporta validazione regex.
F	Nome completo	Precompilato con nome e cognome del firmatario.
1	Nome	Precompilato con il nome del firmatario.
2	Cognome	Precompilato con il cognome del firmatario.
C	Azienda	Nome dell'azienda del firmatario.
X	Email	Precompilato con l'email del firmatario.
K	Telefono	Precompilato con il numero di telefono del firmatario.

Date

Codice	Tipo	Descrizione
D	Data firma	Data in cui viene apposta la firma (precompilato automaticamente).
O	Data e ora firma	Data e ora della firma (precompilato automaticamente).
E	Data di nascita	Data di nascita del firmatario.

Dati Anagrafici

Codice	Tipo	Descrizione
A	Luogo di nascita	Comune di nascita del firmatario.
B	Provincia di nascita	Provincia di nascita.
M	Comune di residenza	Comune di residenza.
N	Indirizzo di residenza	Indirizzo di residenza.
P	Provincia di residenza	Provincia di residenza.
Q	Comune di domicilio	Comune di domicilio.
V	Indirizzo di domicilio	Indirizzo di domicilio.
L	Provincia di domicilio	Provincia di domicilio.

Documento di Identità

Codice	Tipo	Descrizione
J	Numero documento	Numero del documento di identità.
G	Rilasciato da	Ente che ha rilasciato il documento.
H	Data rilascio	Data di rilascio del documento.

Controlli Form

Codice	Tipo	Descrizione
I	Checkbox	Casella di spunta (sì/no).
R	Radio button	Selezione esclusiva tra opzioni (da raggruppare con groupId).
U	Combo box	Menu a tendina con opzioni predefinite (usare autocompleteValues).
Y	Segno di spunta	Croce/spunta visiva sul documento.

Firma e Allegati

Codice	Tipo	Descrizione
S	Firma grafica	Area dove il firmatario disegna la propria firma.
Z	Allegato	Il firmatario deve caricare un file allegato (es. documento di identità).

---

Parametri del Placeholder

Posizionamento

Campo	Tipo	Obbligatorio	Descrizione
document	integer	Sì	Indice del documento (0-based).
page	integer	Sì	Numero della pagina (1-based).
positionX	number	Sì	Posizione orizzontale (0-1, normalizzata).
positionY	number	Sì	Posizione verticale (0-1, normalizzata).
width	number	Sì	Larghezza del campo (0-1).
height	number	Sì	Altezza del campo (0-1).
anchorKeyword	string	No	Parola chiave nel PDF per posizionamento automatico (alternativa a positionX/Y).
offsetX	number	No	Offset orizzontale normalizzato (aggiunto alla posizione calcolata).
offsetY	number	No	Offset verticale normalizzato.

Identificazione e Validazione

Campo	Tipo	Obbligatorio	Descrizione
type	char	Sì	Tipo di placeholder (vedi tabella sopra).
code	string	Consigliato	Codice identificativo univoco del placeholder. Utilizzato per riferimenti e logica condizionale.
required	boolean	No	Se true, il firmatario deve compilare il campo. Default: false.
defaultValue	string	No	Valore predefinito del campo.
regex	string	No	Espressione regolare per la validazione dell'input.
regexErrorMessage	string	No	Messaggio di errore mostrato se la validazione fallisce.
externalId	string	No	ID esterno per mappatura con sistemi esterni.

Aspetto

Campo	Tipo	Obbligatorio	Descrizione
fontSize	integer	No	Dimensione del font in punti.
fontFamily	string	No	Font da utilizzare (es. Helvetica, Courier).
opacity	integer	No	Opacità del testo (0-100).
alignment	char	No	Allineamento del testo: L sinistra, C centro, R destra.
cssCustomClass	string	No	Classe CSS personalizzata per lo stile nell'interfaccia web.

Comportamento

Campo	Tipo	Obbligatorio	Descrizione
readonly	boolean	No	Se true, il campo è in sola lettura (precompilato, non modificabile).
editableSubmit	boolean	No	Se true (default), il campo è modificabile al momento della sottomissione.
groupId	integer	No	ID di gruppo: stesso valore su più placeholder li associa logicamente (es. radio button dello stesso gruppo).

Opzioni per Combo Box

Campo	Tipo	Descrizione
autocompleteValues	string	Opzioni del menu a tendina in formato JSON (array di stringhe o oggetti).
autocompleteValuesList	array[string]	Alternativa: array di valori per autocompletamento.

---

Logica Condizionale

I placeholder supportano visibilità/obbligatorietà condizionale basata sul valore di un altro placeholder:

Campo	Tipo	Descrizione
cfCondition	string	Condizione da valutare: equals, notEquals, contains, isEmpty, isNotEmpty.
cfConditionComparePlaceholder	number	ID del placeholder da confrontare (riferimento).
cfConditionCompareValue	string	Valore di confronto.
cfBehavior	string	Comportamento quando la condizione è vera: show, hide, required, readonly.

Esempio: campo visibile solo se una checkbox è selezionata

[
  {
    "type": "I",
    "code": "accetto_condizioni",
    "document": 0,
    "page": 1,
    "positionX": 0.1,
    "positionY": 0.7,
    "width": 0.03,
    "height": 0.03
  },
  {
    "type": "T",
    "code": "note_aggiuntive",
    "document": 0,
    "page": 1,
    "positionX": 0.1,
    "positionY": 0.75,
    "width": 0.4,
    "height": 0.03,
    "cfCondition": "equals",
    "cfConditionCompareValue": "true",
    "cfBehavior": "show"
  }
]

---

Esempi

Campo testo obbligatorio con validazione

{
  "type": "T",
  "code": "codice_fiscale",
  "document": 0,
  "page": 1,
  "positionX": 0.3,
  "positionY": 0.4,
  "width": 0.25,
  "height": 0.03,
  "required": true,
  "regex": "^[A-Z]{6}[0-9]{2}[A-Z][0-9]{2}[A-Z][0-9]{3}[A-Z]$",
  "regexErrorMessage": "Inserire un codice fiscale valido (es. RSSMRA80A01H501U)",
  "fontSize": 10
}

Menu a tendina

{
  "type": "U",
  "code": "tipo_contratto",
  "document": 0,
  "page": 1,
  "positionX": 0.3,
  "positionY": 0.5,
  "width": 0.2,
  "height": 0.03,
  "required": true,
  "autocompleteValuesList": [
    "Tempo indeterminato",
    "Tempo determinato",
    "Collaborazione",
    "Stage"
  ]
}

Checkbox e data firma automatica

[
  {
    "type": "I",
    "code": "privacy_check",
    "document": 0,
    "page": 2,
    "positionX": 0.05,
    "positionY": 0.85,
    "width": 0.03,
    "height": 0.03,
    "required": true
  },
  {
    "type": "D",
    "code": "data_firma",
    "document": 0,
    "page": 2,
    "positionX": 0.7,
    "positionY": 0.9,
    "width": 0.15,
    "height": 0.03,
    "readonly": true
  }
]

Posizionamento tramite ancora

Anziché specificare coordinate fisse, è possibile posizionare il placeholder cercando una parola chiave nel testo del PDF:

{
  "type": "T",
  "code": "citta",
  "document": 0,
  "anchorKeyword": "Luogo:",
  "offsetX": 0.1,
  "offsetY": 0.0,
  "width": 0.15,
  "height": 0.03
}

Il sistema cerca il testo "Luogo:" nel PDF e posiziona il placeholder con l'offset specificato.