Avviare un processo di firma

Vediamo nel dettaglio le informazioni chieste per l’avvio di un processo di firma

PARAMETRI

I parametri da indicare nella chiamata sono;
- APIKey e APISecret generati dall’utente come indicato alla pagina Generare le api keys
- PartitaIva: La partita iva del cliente (comprensivo del codice paese). E’ obbligatorio se non indicato il Codice fiscale e deve trovare una e una sola corrispondenza tra le aziende censite.
- CodiceFiscale: Il codice fiscale del cliente. E’ obbligatorio se non indicata la Partita Iva e deve trovare una e una sola corrispondenza tra le aziende censite.

CORPO DELLA RICHIESTA

Analizziamo i singoli elementi:

“nomeProcesso”: Nome che il richiedente desidera dare al processo di firma che sta avviando. Questo nome verrà riportato nell’attestato di firma, sarà visibile al firmatario e ricercabile all’interno dell’applicazione web
Lunghezza massima 100 caratteri
“tipoFirma”: indicare 1 per FES, 2 per FEA. Per maggiori dettagli sulle tipologie di firma consultare la pagina Tipologie di firma
“modalitaInvioOtp”: Indicare 1 per SMS, 2 per Whatsapp. Se non indicato il valore di default è SMS
“nomeDocumentoDaFirmare”: “string”, Nome del documento che il richiedente sta inviando in firma
Lunghezza massima 200 caratteri
“documentoDaFirmare”: “string”, codifica base 64 del file da inviare in firma
Dimensione massima 20 MB

FIRMATARI

Il blocco di informazioni relativo ai firmatari contiene i dati obbligatori per il censimento dei firmatari e le informazioni sulle firme che ognuno di essi dovrà apporre. Ogni firmatario indicato verrà automaticamente salvato all’interno dell’anagrafica firmatari di Sifirma.
Se il firmatario è già censito non verrà creato nuovamente ma, se necessario, solo modificato (la chiave è il campo Codice Fiscale).
In caso di firma sequenziale ripetere il blocco di dati per i firmatari necessari, nell’ordine in cui dovranno ricevere il documento.

“nome”: “string”, nome del firmatario che riceverà il documento
Lunghezza massima 60 caratteri
“cognome”: “string”, cognome del firmatario che riceverà il documento
Lunghezza massima 60 caratteri
“tipoIdentificativoFiscale”: campo opzionale per specificare come verrà identificato il firmatario; se non specificato si considera codice fiscale italiano. Indicare 1 se il firmatario verrà identificato con il codice fiscale italiano, 2 se verrà identificato con un tax identification code estero.
“email”: “string”, indirizzo email al quale, se scelto il firmatario riceverà la comunicazione con il link per accedere al documento da firmare e la conferma al completamento della firma. E’ presente una validazione formale sul valore inserito.
“codiceFiscale”: “string”, codice fiscale del firmatario che riceverà il documento. E’ presente una validazione formale sul valore solo se viene inserito un codice fiscale italiano.
“telefono”: “string”, numero di cellulare del firmatario che riceverà il documento. Non è necessario indicare il prefisso (+39). E’ presente una validazione formale sul valore inserito.
“ordineSequenziale”: per ogni firmatario deve essere inserito l’ordine di firma. Il campo è opzionale, se non inserito si considera l’ordine dei firmatari indicati nella chiamata, altrimenti l’ordine indicato in questo campo.

documentoRiconoscimento: Da indicare solo in caso di tipo firma FEA e se non è stato già caricato in precedenza. Se già caricato verrà ignorato a meno che non vengano apportate modifiche sui valori, in quel caso il documento già associato al firmatario verrà modificato.

“file”: “string”, codifica base 64 del documento di riconoscimento
“nomeFile”: “string”, nome del documento di riconoscimento
Lunghezza massima 100 caratteri
“numero”: “string”, numero del documento di riconoscimento
Lunghezza massima 50 caratteri
“tipo”: “string”, tipo del documento di riconoscimento (es. Carta d’identità, passaporto…)
Lunghezza massima 100 caratteri
“dataRilascio”: “2023-06-12T10:23:02.375Z”,
“dataScadenza”: “2023-06-12T10:23:02.375Z”,
“rilasciatoDa”: “string”, ente che ha rilasciato il documento di riconoscimento
Lunghezza massima 100 caratteri
“chiaveCifratura”: “string”, il valore inserito verrà utilizzato per cifrare il documento e solo conoscendo questa chiave sarà possibile riaprire il documento all’interno di sifirma

FIRME

In base al tipo identificatore firma che si desidera utilizzare (marcatori, coordinate o acrofield) utilizzare il blocco firme corretto tra i tre sotto riportati, ripetuto per ogni firma che il firmatario al quale sono legate dovrà apporre.

firmeMarcatore: per ogni firmatario è possibile specificare su quali marcatori, presenti all’interno del documento, dovrà apporre la propria firma e se il firmatario deve apporre o meno la firma grafica.

“firmaGrafica”: da valorizzare con true, se il firmatario deve poter apporre la firma graficamente sul marcatore indicato; false in caso non fosse necessario l’apposizione della firma grafica sul marcatore indicato
“hasOTP”: da valorizzare con true, se il firmatario deve confermare la firma inserendo un OTP ricevuto via SMS; false in caso non fosse necessario confermare la firma inserendo un OTP ricevuto via SMS ma fosse sufficiente il point and click. Il campo è opzionale, se non indicato il valore di default per il tipo firma FES è false, per il tipo firma FEA è true.
“nomeMarcatore”: “string”, riportare il nome del marcatore senza i caratteri ##. Il campo non è case sensitive

firmeCoordinate: per ogni firmatario è possibile specificare quali sono i punti all’interno del documento nei quali il firmatario dovrà apporre la propria firma e se il firmatario deve apporre o meno la firma grafica.

“firmaGrafica”: da valorizzare con true, se il firmatario deve poter apporre la firma graficamente sul marcatore indicato; false in caso non fosse necessario l’apposizione della firma grafica sul marcatore indicato
“hasOTP”: da valorizzare con true, se il firmatario deve confermare la firma inserendo un OTP ricevuto via SMS; false in caso non fosse necessario confermare la firma inserendo un OTP ricevuto via SMS ma fosse sufficiente il point and click. Il campo è opzionale, se non indicato il valore di default per il tipo firma FES è false, per il tipo firma FEA è true.
“pagina”: numero di pagina del documento dove inserire il campo firma
“x”: coordinata x (espressa in punti PT) del punto in alto a sinistra dove inserire il campo firma
“y”: coordinata y (espressa in punti PT) del punto in alto a sinistra dove inserire il campo firma
“altezza”: altezza del campo firma a partire dalla coordinata indicata
“larghezza”: larghezza del campo firma a partire dalla coordinata indicata

firmeAcrofield: per ogni firmatario è possibile specificare quali sono gli acrofield inseriti all’interno del documento nei quali il firmatario dovrà apporre la propria firma e se il firmatario deve apporre o meno la firma grafica.

“firmaGrafica”: da valorizzare con true, se il firmatario deve poter apporre la firma graficamente sul marcatore indicato; false in caso non fosse necessario l’apposizione della firma grafica sul marcatore indicato
“hasOTP”: da valorizzare con true, se il firmatario deve confermare la firma inserendo un OTP ricevuto via SMS; false in caso non fosse necessario confermare la firma inserendo un OTP ricevuto via SMS ma fosse sufficiente il point and click. Il campo è opzionale, se non indicato il valore di default per il tipo firma FES è false, per il tipo firma FEA è true.
“nome”: “string”, riportare il nome dell’acrofield presente all’interno del documento pdf. Il campo è Case Sensitive

ALTRE INFORMAZIONI

“dataScadenza”: “2023-06-12T10:23:02.375Z”, data entro cui il firmatario dovrà provvedere alla firma del documento. Non ci sono limiti nella data che può essere indicata
“inviaMail”: da valorizzare con true, se si desidera inviare la mail al firmatario per l’accesso asincrono al processo di firma; false per non inviare la mail, nè per l’accesso al documento da firmare, nè di esito della firma.
“urlRedirect”: “string”, indirizzo al quale il firmatario viene reindirizzato al termine del processo di firma. Questo dato è facoltativo. A questo indirizzo vengono restituite le seguenti informazioni:
- UID della richiesta da cui il firmatario è stato reindirizzato
- stato richiesta: Rifiutato = 9; Completato = 4
Le informazioni vengono restituite sotto forma di parametri di query e i nomi utilizzati per identificare questi due parametri sono rispettivamente “uid_richiesta” e “stato_richiesta”.
“webHookCallback”: “string”, indirizzo al quale sifirma effettua una chiamata in POST quando il firmatario ha completato il processo di firma, se lo ha rifiutato o quando scade. Questo dato è facoltativo. A questo indirizzo vengono restituite le seguenti informazioni:
- UID della richiesta da cui il firmatario è stato reindirizzato
- stato richiesta: Rifiutato = 9; Completato = 4; Scaduto = 6
- i metadati che possono essere impostati in fase di avvio del processo di firma

Le informazioni vengono restituite sotto forma di JSON che sarà della seguente forma:
{ UIDProcesso = “00000000-0000-0000-0000-000000000000”,
UIDRichiesta = “00000000-0000-0000-0000-000000000000”,
UIDNuovaRichiesta = “00000000-0000-0000-0000-000000000000”, (se il cambio stato riguarda la creazione di una nuova richiesta in sostituzione della precedente scaduta)
Firmatario: (oggetto contenente i dati del firmatario, relativo alla richiesta che ha cambiato stato)
{ Nome: “string”, Cognome: “string”, Email: “string”, CodiceFiscale: “string”, Telefono: “string”
}

StatoRichiesta = 4,
“StatoProcesso”: 4,
“MotivoRifiuto”: “string”
“DocumentoFirmatoFileUrl”: “https://…”, (url temporaneo con validità di 1 minuto)
“AttestatoFirmaFileUrl”: “https://…”, (url temporaneo con validità di 1 minuto)
“MarcaTemporaleFileUrl”: “https://…”, (url temporaneo con validità di 1 minuto)
“LogAuditFileUrl”: “…”, (url temporaneo con validità di 1 minuto) Metadati = “test”}

“metadati”: “stringtextileRef:9841035906aac86bbbc4a4:linkStartMarker:”, campo libero, dove il richiedente può inserire tutte le informazioni necessarie al riconoscimento del processo di firma, ad esempio identificativi specifici ecc… Questa informazione viene restituita chiedendo lo stato del processo.
“ tipoIdentificatoreFirma”: indicare 2 per coordinate, 3 per acrofield, 4 per la V2 dei marcatori. In base all’identificatore scelto dovrà essere inserito almeno un blocco firma per ogni firmatario indicato della tipologia corretta. (NON INSERIRE IN CASO DI TIPOLOGIA FIRMA=FEQ)

INFORMAZIONI PER CONSERVAZIONE A NORMA

- daConservare: da valorizzare con true, se si desidera avviare la conservazione al termine del processo di firma, una volta completato; false se non si intende conservare il documento. Il flag è opzionale, se non passato si intende false.
- tipoDocumentoConservazione: solo se il documento deve essere conservato, è obbligatorio indicare il tipo documento inviato in firma, scegliendo tra: – Preventivi = 1, – Offerte = 2, – Ordini = 3, – DDT = 4, – Contratti = 5, – Informative = 6, – DocumentiPrivacy = 7, – DocumentiAmministrativiFiscali = 8, – AltriDocumenti = 9
- numeroDocumentoConservazione: solo se il documento deve essere conservato, è obbligatorio indicare il numero del documento inviato in firma.

NOTE SULL’UTILIZZO DI MARCATORI E ACROFIELD

- Solo per i marcatori: Nel documento, i marcatori devono essere indicati tra due caratteri cancelletto, ad esempio: ##FIRMA##. Nella chiamata API devono essere passati come semplice stringa, senza i caratteri cancelletto, ad esempio: FIRMA.
- non sono case-sensitive, quindi non importa se scritti in maiuscolo o minuscolo.
- E’ possibile inviare il documento in formato word o PDF
- Marcatori e acrofield presenti nel documento che non sono associati ad alcun firmatario nella chiamata API verranno ignorati e rimossi automaticamente.
- Marcatori e acrofield inclusi nella chiamata API ma assenti nel documento saranno anch’essi ignorati e rimossi.
- Se nel documento sono presenti più Marcatori o acrofield con lo stesso nome per lo stesso firmatario, è sufficiente indicarlo una sola volta nella chiamata API. Ogni occorrenza di quel Marcatori o acrofield rappresenterà un campo firma per il firmatario.
- Devono essere univoci: non è consentito inserire più Marcatori o acrofield identici nella chiamata API, né per lo stesso firmatario né per firmatari diversi.
- Se nel documento non sono presenti marcatori o acrofield o non viene trovata corrispondenza tra marcatori e acrofield indicati nella chiamata API e quelli effettivamente presenti, il firmatario non visualizzerà alcun pulsante di firma. In tal caso, potrà semplicemente scorrere il documento e completare il processo di firma.

RISPOSTA

Durante la creazione del processo di firma vengono fatti i controlli necessari:

Data scadenza: deve essere successiva alla data odierna
Campi obbligatori: tutti i campi obbligatori devono essere presenti e formalmente corretti

Se i controlli danno esito negativo, si ottiene una risposta con il relativo messaggio di errore;
Se i controlli danno esito positivo, si ottiene in risposta: