eSignature

I Certificati di Firma automatica e massiva, con o senza OTP, possono essere acquistati rispettivamente tramite gli endpoint

• POST /certificates/namirial-automatic
• POST /certificates/namirial-otp

Una volta effettuata la richiesta tramite API, nella risposta sarà disponibile il link per poter avviare la procedura di identificazione, secondo la normativa vigente, del richiedente e ottenere così il rilascio del certificato.

Il nostro servizio include nel prezzo il video riconoscimento, da effettuare comodamente da casa o dall'ufficio, in pochi secondi. In alternativa, sono disponibili altre procedure di identificazione tramite:

• SPID
• CIE
• CNS
• Firma digitale

NOTA BENE: L’acquisto del certificato è indispensabile per poter utilizzare il servizio di Firma Elettronica Qualificata Automatica e Massiva (con o senza OTP).

Il certificato ha una validità di 3 anni.

Le credenziali CERT_USERNAME e CERT_PASSWORD non vengono rilasciate immediatamente dopo l'acquisto del certificato di firma QES. Per ottenerle è necessario completare la procedura di identificazione del titolare del certificato.

Dopo aver effettuato la richiesta di acquisto tramite gli endpoint POST /certificates/namirial-automatic o POST /certificates/namirial-otp, la risposta API restituisce il campo certificateLink, che contiene l'URL da utilizzare per avviare il processo di identificazione. La procedura richiede generalmente pochi minuti e deve essere completata direttamente dall'intestatario del certificato.

Al termine dell'attivazione, le credenziali vengono inviate attraverso canali separati per garantire il massimo livello di sicurezza:

• SMS contenente il PIN;
• E-mail contenente il CERT_USERNAME con allegato PDF protetto da password contenente il CERT_PASSWORD.

Per aprire il PDF e visualizzare il CERT_PASSWORD, è necessario utilizzare il PIN ricevuto via SMS.

La separazione dei canali di consegna delle credenziali riduce il rischio di accessi non autorizzati e garantisce una maggiore protezione del certificato di firma.

Se non ricevi l'e-mail con le credenziali, verifica anche la cartella Spam/Posta indesiderata e assicurati che l'indirizzo e-mail fornito durante la richiesta del certificato sia corretto.

L'acquisto del QESeal (disponibile con validità 1 o 3 anni) richiede attualmente una procedura manuale tramite il supporto clienti.

Segui questi step:

1. Contatta il supporto clienti per avviare la richiesta di acquisto.
2. Completa l'acquisto secondo le indicazioni del supporto e ricevi il modulo di identificazione via email.
3. Invia la documentazione richiesta per il processo di identificazione:

• documento di identità
• visura camerale (o equivalente, in base al Paese dell'azienda richiedente)
• modulo compilato (ricevuto al punto 2)

4. Ricevi le credenziali del certificato (certificateUsername e certificatePassword) all'indirizzo email indicato nel modulo. certificateUsername è una stringa con prefisso SHI.

NOTA BENE: L’acquisto del sigillo è indispensabile per poter utilizzare il servizio QESeal su Openapi.

Puoi effettuare il processo di firma via API tramite gli endpoint

• POST/EU-QES_automatic con il Certificato di Firma automatico massivo
• POST/EU-QES_OTP con il Certificato remoto con OTP
• POST/EU-QES_eseal con il Sigillo Elettronico Qualificato

I campi obbligatori per procedere alla firma elettronica qualificata sono tre:

• Documento (inputDocument)
• Username del Certificato di Firma
• Password del Certificato di Firma

Se non viene specificato (nel campo signatureType), il sistema cercherà il formato (CAdES, PAdES, XAdES e PKCS#1) più adatto in base al mimeType del file caricato.

I servizi QES OTP e QES Automatic supportano diversi standard di firma elettronica qualificata, ciascuno progettato per specifiche tipologie di documenti e casi d'uso:

• CAdES (CMS Advanced Electronic Signatures): consente di firmare qualsiasi tipologia di file. Il documento firmato viene generalmente generato con estensione .p7m, che incorpora il file originale e la firma digitale.
• PAdES (PDF Advanced Electronic Signatures): dedicato ai documenti PDF. Mantiene l'estensione .pdf e permette di visualizzare la firma direttamente all'interno del documento.
• XAdES (XML Advanced Electronic Signatures): specifico per documenti XML, particolarmente utilizzati negli scambi di dati tra applicazioni e sistemi informativi.
• PKCS#1: non rappresenta un formato di firma documentale, ma uno standard crittografico basato su RSA utilizzato per firmare hash o dati a livello applicativo.

In sintesi, CAdES, PAdES e XAdES definiscono il formato e le modalità con cui la firma digitale viene applicata a documenti di diverso tipo, mentre PKCS#1 definisce il meccanismo crittografico utilizzato per generare e verificare la firma stessa. La scelta dello standard dipende dal formato del documento e dalle esigenze di integrazione del processo di firma.

Nota: in base allo standard di firma selezionato (CAdES, PAdES, XAdES o PKCS#1), saranno disponibili specifiche opzioni di configurazione aggiuntive che possono essere impostate durante la richiesta di firma tramite il campo option del payload.

Tali opzioni consentono, ad esempio, di personalizzare il comportamento della firma, il formato del documento risultante e altri parametri specifici dello standard utilizzato.

Per conoscere nel dettaglio tutte le opzioni disponibili, i relativi valori supportati e le modalità di utilizzo, ti invitiamo a consultare la documentazione tecnica e lo schema API associato allo standard di firma selezionato. Questo ti permetterà di configurare correttamente il servizio in base alle tue esigenze di integrazione.

Il regolamento europeo eIDAS (Electronic Identification, Authentication and Trust Services) distingue tre livelli di firma elettronica, ciascuno con caratteristiche e valore legale differenti:

Firma Elettronica Semplice (SES)
È la forma più basilare di firma elettronica. Consente di associare un'azione o un consenso a un utente, ma offre un livello limitato di garanzie sull'identità del firmatario. È comunemente utilizzata per accettare termini e condizioni, confermare operazioni online o accedere a servizi digitali.

Firma Elettronica Avanzata (AES)
Garantisce un collegamento univoco tra il firmatario e il documento sottoscritto, consentendo di identificare il firmatario e di rilevare eventuali modifiche successive al documento. In molti casi può avere la stessa efficacia giuridica della firma autografa ed è adatta alla sottoscrizione di contratti e scritture private.

Firma Elettronica Qualificata (QES)
È il livello più elevato di firma elettronica previsto dal regolamento eIDAS. Rilasciata tramite un certificato qualificato da un prestatore di servizi fiduciari qualificato, offre il massimo livello di sicurezza e ha pieno valore legale in tutta l'Unione Europea. In Italia è comunemente associata alla firma digitale.

Quale Sceglere?

Nota: le informazioni riportate hanno carattere generale e non costituiscono consulenza legale. La scelta della tipologia di firma più adatta dipende dal contesto normativo, dal livello di rischio e dalle specifiche esigenze del proprio business. Per individuare la soluzione più appropriata, è consigliabile confrontarsi con il proprio team legale o con consulenti specializzati.

La procedura di firma ha validità legale (eIDAS) ed è rafforzata dall’invio di OTP di verifica dei firmatari. Alla fine della procedura di firma sarà possibile inoltre richiedere tramite API sia il documento firmato che la copia dell'audit trail. L'audit trail è il documento che contiene tutte le informazioni che hanno portato al buon esito della firma. Nel caso di controversie, questo file permetterà di riprodurre tecnicamente ogni passaggio della procedura. 

L'audit trail contiene dati su procedura (id, data creazione, invio e scadenza), su firmatari (nome, cognome, email, numero di telefono, indirizzo IP) modalità di autenticazione firmatari (metodo di autenticazione, messaggio inviato e ora di convalida). L'audit trail viene archiviato in originale per 10 anni.

 Il servizio consente di configurare diverse opzioni, tra cui:

• Modalità di validazione e firma (sincrona o asincrona)
• Livello di firma
• Algoritmo di hash
• Callback per notifiche e aggiornamenti

Alcune opzioni sono disponibili solo per formati specifici, come il posizionamento della firma all'interno di documenti PDF.

Il servizio di firma elettronica (SES) consente di firmare documenti PDF a distanza in modo semplice, sicuro e conforme agli standard normativi vigenti. È possibile coinvolgere più firmatari sullo stesso documento, anche con posizionamenti differenti della firma all’interno delle pagine.

Il processo si articola nei seguenti passaggi:

1. Invio della richiesta tramite API
Effettua una chiamata API includendo i dati dei firmatari (nome e cognome), la tipologia di firma da applicare (typed o drawn), il metodo di autenticazione OTP (email o SMS) e la lingua dell’interfaccia e delle comunicazioni OTP. In base al metodo di autenticazione selezionato, sarà necessario fornire anche l’email o il numero di cellulare del firmatario.

2. Generazione dei link di firma
Il sistema restituisce link univoci per ciascun firmatario, da utilizzare per accedere al processo di firma. Sarà vostra responsabilità distribuire i link ai rispettivi firmatari e gestire l’invio dell’interfaccia di firma.

3. Firma del documento
I firmatari accedono alla piattaforma tramite il link ricevuto, completano l’autenticazione OTP e procedono con l’apposizione della firma sul documento.

4. Completamento del processo e download
Al termine del processo, il documento firmato e validato viene reso disponibile per il download, insieme al registro completo delle operazioni (audit trail), che garantisce la tracciabilità dell’intero flusso di firma.

 La risposta dipende dallo stato della richiesta e può essere:

• In attesa di convalida
• In attesa del completamento del processo di firma
• Processo di firma completato

In caso di esito positivo (“DONE), la risposta includerà dettagli sullo stato, il formato di firma, le opzioni scelte (es. livello di firma, hash algoritmo, eventuale callback) e la data di completamento.

Entrambe. Infatti il servizio di Firma Elettronica Qualificata (QES) via API consente di scegliere se la validazione del documento e la firma debbano essere sincroni o asincroni.

Sì, il servizio supporta l'apposizione di qualsiasi tipologia di marca temporale, offrendo un ulteriore livello di sicurezza e validità legale ai documenti firmati.

Sì, i servizi QES OTP e QES Automatic consentono di personalizzare il posizionamento della firma all'interno del documento, specificando la pagina su cui apporla oppure i campi firma da utilizzare.

Nota: questa funzionalità è disponibile esclusivamente per le firme in formato PAdES, l'unico formato che prevede una firma visibile direttamente sul documento PDF.

Se non viene specificata alcuna configurazione, la firma viene posizionata automaticamente nell'angolo inferiore sinistro della prima pagina.

Per personalizzare il posizionamento della firma tramite l'endpoint /EU-QES_otp o /EU-QES_automatic, è possibile utilizzare i parametri disponibili nell'oggetto options del payload della richiesta.

1. Posizionamento tramite pagina (page)

Puoi indicare la pagina del PDF in cui creare il campo firma e applicare la firma digitale:

• 1 → prima pagina del documento
• 2 → seconda pagina del documento
• -1 → ultima pagina del documento

Ad esempio, impostando page: -1, la firma verrà inserita automaticamente nell'ultima pagina del PDF.

Quando viene utilizzato questo parametro, la firma viene sempre posizionata nell'angolo inferiore sinistro della pagina selezionata.

2. Firma di tutti i campi presenti nel documento (signAllFields)

Se il documento contiene uno o più campi firma predefiniti, puoi impostare nel campo "signerImage":

"signAllFields": true

In questo modo la firma verrà applicata automaticamente a tutti i campi firma presenti nel PDF.

3. Firma di specifici campi (fieldsNameList)

Se desideri firmare solo determinati campi, puoi utilizzare il parametro fieldsNameList all'interno dell'oggetto signerImage.
Il parametro deve contenere un array con gli identificativi dei campi firma da utilizzare:

"fieldsNameList": [
"FirmaCliente",
"FirmaContraente"
]

La firma verrà applicata esclusivamente ai campi indicati nell'array.

Sì, attraverso l’endpoint GET /signatures/{id}/{actionType} al termine della procedura di firma è possibile richiedere il dettaglio completo del processo, il documento firmato, il documento validato o l'audit trail. Quest'ultimo include tutte le informazioni che hanno portato al buon esito della firma e permette di ricostruire tecnicamente ogni passaggio della procedura in caso di controversie.

Sì, è possibile personalizzare l’interfaccia di firma SES per l’utente finale già in fase di richiesta.

La personalizzazione può includere, ad esempio, la modifica dei colori (del background, del titolo e del testo) e della visibilità di sidebar, header e footer, oltre all’inserimento del proprio logo aziendale. È inoltre possibile abilitare o disabilitare il download del documento da parte dell’utente.

Infine, al termine del processo di firma, è possibile configurare un URL di redirect verso una pagina web personalizzata.

Sì, è possibile impostare la lingua dell’interfaccia di firma SES a livello di singolo firmatario.

La lingua con cui l’utente visualizza l’interfaccia e riceve le comunicazioni (email o SMS contenenti l’OTP) può essere definita tramite il campo “Language” presente nell’oggetto Signers.

Sì. Il servizio SES consente di definire se i dati del firmatario possano essere modificati durante il processo di firma tramite l'oggetto userEditableData, disponibile all'interno dell'oggetto options nella richiesta POST /EU-SES.

Per impostazione predefinita, i firmatari possono modificare alcuni dati personali, quali:

• Nome e cognome
• Indirizzo email
• Numero di cellulare

Queste opzioni sono abilitate di default e impostate a true.

Se desideri impedire ai firmatari di modificare uno o più campi, è sufficiente impostare le relative proprietà a false. In questo modo i dati verranno visualizzati in modalità di sola lettura all'interno dell'interfaccia di firma e non potranno essere modificati dall'utente.

Questa funzionalità è particolarmente utile quando si desidera garantire che i dati raccolti e verificati a monte rimangano invariati durante l'intero processo di firma.

L’errore 815 – invalid signer email viene restituito quando l’indirizzo email del firmatario non è valido oppure non è stato fornito correttamente nella richiesta.

Per risolvere il problema, ti consigliamo di verificare che il valore passato sia formalmente corretto e privo di spazi non desiderati prima o dopo l’indirizzo email.

In particolare, suggeriamo di implementare le seguenti validazioni lato client prima dell’invio della richiesta API:

1. Controllo sintattico (formato email)
Verifica che la stringa inserita rispetti un formato email valido (es. [email protected]).
Se il formato non è corretto, blocca l’invio della richiesta direttamente nell’interfaccia utente, evitando la chiamata API.

2. Pulizia della stringa
Assicurati di rimuovere eventuali spazi iniziali o finali applicando una normalizzazione del tipo .trim() sul valore dell’email.

3. Validazione preventiva del form
Per ridurre al minimo gli errori, è consigliabile impedire l’invio del form finché la validazione non è completata con successo, evitando così richieste API non valide.

E' possibile verificare la validità della firma di un documento tramite l’endpoint POST /verify.

La risposta includerà informazioni come:

• Conferma della validità della firma e del formato utilizzato
• Proprietario del documento
• Stato e data del certificato
• Eventuale revoca del certificato con relativa data
• Presenza e data di una marcatura temporale

I tempi di attivazione e utilizzo dei servizi eSignature variano in base alla tipologia di firma o certificato richiesto:

• QES Automatico (con o senza OTP): l'attivazione del certificato dipende dal completamento della procedura di identificazione tramite videoriconoscimento, che nella maggior parte dei casi richiede solo pochi minuti.
• QESeal (Sigillo Elettronico Qualificato): l'emissione del certificato richiede generalmente fino a 10 giorni lavorativi dalla ricezione del pagamento e di tutta la documentazione necessaria per le verifiche preliminari.
• SES (Firma Elettronica Semplice): l'identificazione del firmatario avviene in tempo reale durante il processo di firma tramite verifica OTP.
• Apposizione della firma o del sigillo: una volta completata l'attivazione del servizio, l'apposizione della firma automatica, della firma con OTP, della firma semplice (SES) o del sigillo elettronico avviene in tempo reale tramite API.

Nella sezione Utilizzo, a livello di API, è possibile monitorare le richieste gratuite ed effettuate tramite abbonamento o ricarica. Sono disponibili sia in modalità grafica (periodo mese e anno), sia con un riepilogo testuale.

Il servizio di Firma QES non ha canoni annuali; è previsto il pagamento solo per l’attivazione del certificato e per gli utilizzi effettivi.

I costi relativi alle chiamate sono:

• a partire da 0,013€ su abbonamento e 0,050€ su ricarica per il servizio con certificato di firma automatica
• a partire da 0,007€ su abbonamento e 0,050€ su ricarica per il servizio con certificato di firma automatica con OTP

I costi relativi ai certificati invece sono i seguenti:

• 137€ per il certificato di firma automatica 3 anni + video id
• 29€ per il certificato di firma automatica 3 anni con OTP + video id

Il servizio non ha canoni annuali. È previsto il pagamento solo per l’attivazione del sigillo e per gli utilizzi effettivi.

Per quanto riguarda gli utilizzi, il costo è a partire da 0,013€/chiamata su abbonamento o 0,050€/chiamata su ricarica.

Relativamente al sigillo, è possibile richiedere l'attivazione per 1 o 3 anni e i costi sono di 387€ per 1 anno, di 987€ per 3 anni.

Il costo è per firmatario, non per numero di firme apposte sul documento:

• A partire da €0,09 per firmatario con piano in abbonamento
• €0,49 per firmatario per le richieste singole con addebito su ricarica

Se ci sono più firmatari, il costo viene moltiplicato per il numero di firmatari coinvolti, applicando la tariffa prevista (abbonamento o richiesta singola). L’addebito avviene al momento della richiesta, indipendentemente da come si concluderà il processo di firma.

Durante la firma è possibile aggiungere una marcatura temporale con validità europea al costo aggiuntivo di €0,15 per firmatario.