Come creare il Dossier per la richiesta di firma

In questo tutorial vedremo come creare il Dossier, un contenitore che identifica l'insieme dei metadati dei documenti da firmare all'interno di una richiesta di firma.

Ciascun dossier rappresenta uno specifico caso d’uso. Ad esempio, potresti creare un dossier per i documenti delle borse di studio, “Richiesta Borsa di studio”, e un altro “Contratto di assunzione” per i contratti di collaborazione sulla didattica. In questo modo, è possibile creare le richieste di firma verso gli utenti riutilizzando lo stesso dossier.

Infatti, tutti gli studenti e le studentesse che dovranno firmare dei contratti per richiedere una borsa di studio potranno ricevere una signature request creata a partire dallo stesso dossier (in questo esempio, “Richiesta Borsa di studio”).

Il titolo del dossier sarà anche riportato nel messaggio di richiesta di firma al cittadino:

Queste le caratteristiche principali di un dossier:

Può essere riutilizzato, infatti non è legato a specifici utenti, né a uno specifico documento: infatti, non contiene il file PDF
Consente di "raggruppare" le richieste di firma per visualizzare rapidamente determinati dati (e.g., quanti contratti di assunzione sono stati mandati in firma)
Consente di ridurre il numero di chiamate necessarie alla creazione della richiesta di firma
Diminuisce la possibilità di duplicare informazioni durante una richiesta di firma

Creiamo il dossier

Il titolo

Il titolo del dossier deve essere breve e sintetizzare l'oggetto per cui si chiede la firma (es. Carta d'Identità, Contratto di RIcerca...)

deve essere lungo al massimo 75 caratteri, spazi inclusi
deve essere scritto in lettere minuscole e non maiuscole, a meno che non si tratti di sigle o acronimi (es. Carta d'Identità e non CARTA D'IDENTITÀ)
non deve contenere sigle o acronimi poco noti
non deve contenere le parole "online" o "digitale", ma nemmeno parole come "notifica" o "servizio".

Un esempio

Ecco un esempio di chiamata verso l'endpoint:

1POST /api/v1/sign/dossiers
2

Immaginiamo di dover creare un Dossier per la firma di un Contratto 150 ore ("title":"Contratto 150 ore").

Il Dossier prevede un solo documento ("title":"Contratto"), il quale a sua volta richiede una sola firma ("title":"Firma contratto") obbligatoria ("type":"REQUIRED") da parte dell'utente.

Vuoi aggiungere ulteriori documenti al dossier?

Un dossier può essere composto da più documenti. Puoi mandare in firma più documenti PDF in una singola richiesta, inserendo all'interno della lista documents_metadata un oggetto per ogni documento.

Vuoi aggiungere una email di assistenza specifica per il dossier?

Nella fase di creazione di un dossier, hai la possibilità di inserire una email di assistenza specifica per quel dossier. Support_email è un campo opzionale. Nel caso in cui non venga specificato, come email di assistenza verrà utilizzata di default quella inserita in fase di onboarding.

Hai creato i campi firma tramite coordinate?

In questo caso, il corpo del messaggio sarà:

1{
2   "title": "Contratto 150 ore",
3   "documents_metadata":[
4      {
5         "title":"Contratto",
6         "signature_fields":[
7            {
8               "clause":{
9                  "title":"Firma contratto",
10                  "type":"REQUIRED"
11               },
12               "attrs":{
13                  "coordinates":{
14                     "x":360,
15                     "y":100
16                  },
17                  "size":{
18                     "w":170,
19                     "h":30
20                  },
21                  "page":1
22               }
23            }
24         ]
25      }
26   ],
27   "support_email": "demo@assistenza.it"
28}
29

Non hai creato i campi firma (firma trasparente)?

In questo caso, il corpo del messaggio sarà:

1{
2   "title": "Contratto 150 ore",
3   "documents_metadata":[
4      {
5         "title":"Contratto",
6         "signature_fields":[]
7      }
8   ]
9}
10

In tutti i casi, all'interno della risposta riceverai il Dossier creato con il relativo ID associato (dossier_id).

1{
2   "id":"01GG4NFBCN4ZH8ETCCKX3766KX",
3   "title": "Contratto 150 ore",
4   "documents":[
5      {
6         "title":"Contratto",
7         "signature_fields":[]
8      }
9   ]
10}
11

Prendi nota del dossier_id: ti servirà in una fase successiva.

Come indicare se le firme sono obbligatorie, facoltative o vessatorie?

Per indicare che la firma è obbligatoria, inserisci il "type":"REQUIRED"
Per indicare che la firma è vessatoria, inserisci il "type":"UNFAIR"
Per indicare che la firma è facoltativa, inserisci il "type":"OPTIONAL"

Serve aiuto durante l’integrazione?

Scrivi un’e-mail in cui descrivi il tuo problema o dubbio all’indirizzo firmaconio-tech@pagopa.it

Assistenza continua

Per problemi o dubbi dopo l’integrazione, scrivici all’indirizzo enti-firmaconio@assistenza.pagopa.it