Firma Elettronica Qualificata Automatica con OTP

La Firma Elettronica Qualificata (QES) Automatica con OTP è la soluzione via API che permette di automatizzare e semplificare i processi di firma, nel pieno rispetto delle normative europee.

L'autenticazione forte, tramite l'uso delle One Time Password, eleva il livello di sicurezza della firma elettronica e garantisce una protezione aggiuntiva ai documenti firmati.

Il servizio è flessibile e personalizzabile. In particolare permette di scegliere

Non ci sono canoni annuali: l'unico costo fisso è quello di attivazione del certificato (99€). Successivamente, si pagano solo gli utilizzi effettivi.

La Firma Elettronica Qualificata Automatica è disponibile su Openapi anche per persone giuridiche, attraverso un servizio apposito (Sigillo Elettronico Qualificato).

La firma elettronica ha piena validità europea: è infatti riconosciuta dalla legge dell’Unione Europea tramite la regolamentazione eIDAS.

Questa soluzione può essere integrata tramite API in gestionali, software e siti web, per rendere immediata e sicura la firma di grandi volumi di documenti.

Prima di iniziare ad utilizzare la Firma Elettronica Qualificata con OTP è necessario acquistare un certificato di firma tramite l'endpoint dedicato POST /certificates/namirial-otp. Per la procedura di identificazione, è incluso nel prezzo il video riconoscimento, che può essere effettuato dall'ufficio o da casa, in pochi secondi. In alternativa, sono disponibili altre procedure di identificazione tramite SPID, CIE, CNS, Firma digitale.

Dopo l'attivazione del certificato, sarà possibile iniziare ad utilizzare il servizio specifico di firma automatica, disponibile via API sia con OTP sia senza OTP (in quest’ultimo caso l’endpoint di riferimento è EU-QES_automatic).

Richiesta di Firma Elettronica Qualificata con OTP (EU-QES_otp)

POST/EU-QES_otp

L'endpoint POST/EU-QES_otp consente di procedere all'apposizione della firma elettronica qualificata via API.

{
 "inputDocument":[
  {
  	"sourceType": "remote",
	  "url": "https://my-domain.com/remoteResource.pdf",
  },
  {
	  "sourceType": "remote",
	  "payload": "BASE64string",
  }
],
 "certificateUsername": "[email protected]",
 "certificatePassword": "password123",
 "title": "PAdES Signature",
 "description": "Firma PAdES di un file remoto e base64",
 "signatureType": "pades",
}

I campi obbligatori per procedere alla firma sono:

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.

Come detto sopra, il servizio è estremamente flessibile e permette - tramite le diverse opzioni - di configurare ad esempio modalità di validazione e firma del documento (sincrono o asincrono), livello di firma, hash algoritmo, eventuale callback.

Alcune delle opzioni potrebbe essere disponibili solo per formati specifici di firme (es. posizionamento della firma nel documento pdf).

Inoltre, il servizio consente di procedere alla marcatura del documento con qualsiasi tipologia di marca temporale.

Risposta di Firma Elettronica Qualificata con OTP (EU-QES_otp)

POST/EU-QES_otp

Il contenuto della risposta successivo alla richiesta dipenderà chiaramente dallo stato della richiesta e potrà essere:

Nel caso di completamento del processo di firma la risposta conterrà dati come stato (DONE), le opzioni, la data:

{
 "data":{
   "id": "67af252164f60538280f70f9",
	 "updatedAt": "2025-02-14 11:12:53.699+00:00",
   "createdAt": "2025-02-14 11:12:34.218+00:00",
   "certificateType": "EU-QES_automatic",
   "state": "DONE",
   "signatureType": "pades",
   "options": {
     "asyncDocumentsValidation": false,
     "asyncSignature": false,
     "level": "B",
     "hashAlgorithm": "SHA256",
     "encryptInAnyCase": false,
     "page": 1,
     "withSignatureField": false,
  },
    "document": {
    "title": "B",
    "description": "",
    "inputDocuments": [
     {
      "sourceType": "base64",
      "createdAt": "2025-02-14 11:12:33.819+00:00",
      "mimetype": "application/pdf",
      "extension": "pdf",
      "size": 339,
      "id": "67af252164f60538280f70fb",
      "md5": "694be78a9eaa52d602bec92e211fa5dc",
      "name": "694be78a9eaa52d602bec92e211fa5dc.pdf",
    }  
  ],
   "validatedDocument": {,
     "mimetype": "application/pdf",
     "extension": "pdf",
     "size": "339",
     "createdAt": "2025-02-14 11:12:33.819+00:00",
     "id": "67af252164f60538280f70fb",
     "md5": "694be78a9eaa52d602bec92e211fa5dc",
     "name": "694be78a9eaa52d602bec92e211fa5dc.pdf"
}
  "signedDocument": {,
     "createdAt": "2025-02-14 11:12:34.229+00:00",
     "mimetype": "application/pdf",
     "extension": "pdf",
     "size": "50133",
     "id": "67af252264f60538280f70fe",
     "md5": "363cfdb141fe0e1a3f598e1d6377a4f5",
     "name": "67af252164f60538280f70f9.pdf"
    }
  }
}, 
"message": "Created",
"success": true,
"error": null,
}

Audit

GET /signatures/{id}/{actionType}

Quando la procedura di firma è completata, è possibile richiedere il dettaglio del processo di firma ultimato, il documento firmato, il documento validato o 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.

Verifica validità della firma

POST /verify

Openapi offre anche la possibilità di verificare se un documento è stato effettivamente firmato, a chi è associata la firma e per quanto tempo è valida. L’endpoint di riferimento in questo caso è POST /verify.

ESEMPIO RICHIESTA

In fase di richiesta è necessario caricare il documento firmato.

{
  "inputDocument": "BASE64string",
  "detachedContent": "BASE64string",
  "pdfEncryptionPassword": "password123",
  "recursive": true,
  "verifyOnDate": "2025-02-14"
}

ESEMPIO RISPOSTA

Il sistema restituirà diverse informazioni sul documento. In primis, specifica se il documento è stato correttamente firmato, in quale formato, e se la firma è valida.

Inoltre indica:

{
  "data": {
    "checkDate": "2025-02-14 11:11:01.892+00:00",
    "verificationDate": "2025-02-14 11:11:01.892+00:00",
    "signatureFormat": "PAdES",
    "nrOfSignatures": 1,
    "overallVerified": true,
    "signatureReportList": [
      {
        "id": "0",
        "integrity": true,
        "signatureAlgorithmName": "SHA256withRSA",
        "subjectDN": "C=IT,SURNAME=ROSSI,GIVENNAME=MARIO,SERIALNUMBER=TINIT-RSSMRA73R02H501H,CN=ROSSI MARIO,DNQ=AUSL2023021972028357",
        "issuerDN": "C=IT,O=Namirial S.p.A./02046570426,OU=Certification Authority,CN=Namirial CA Firma Qualificata",
        "subjectCN": "ROSSI MARIO",
        "issuerCN": "Namirial CA Firma Qualificata",
        "serialNumber": "5557601230250214000",
        "signerCertificateStatus": "VALID",
        "signerCertificateNotBefore": "2025-02-14 11:11:01.892+00:00",
        "signerCertificateNotAfter": "2025-02-14 11:11:01.892+00:00",
        "signerCertificateRevocationDate": "2025-02-14 11:11:01.892+00:00",
        "issuerCertificateStatus": "VALID",
        "issuerCertificateRevocationDate": "2025-02-14 11:11:01.892+00:00",
        "trustedSignatureDate": false,
        "signatureDate": "2025-02-14 11:11:01.892+00:00",
        "issuerTrustedList": true,
        "keySize": 2048,
        "qcComplianceStatus": "VALID",
        "qcSSCDStatus": "VALID",
        "derEncodedSignerCert": "BASE64string"
      }
    ],
    "noteReportList": [
      {
        "policy": 3,
        "about": 2,
        "type": 1,
        "synopsis": "Certified qualified in conformity",
        "description": "The qualified certificate of ROSSI MARIO complies with European Directive 1999/93/EC"
      }
    ],
    "plainDocument": "BASE64string"
  },
  "message": "Signature is valid",
  "error": null,
  "success": true
}

La firma elettronica qualificata automatica è pensata per coloro che necessitano di firmare un gran numero di documenti quotidianamente e in modalità massiva (es. amministratori, medici, studi legali, enti pubblici). I principali benefici di questa tipologia firma includono il risparmio di tempo e costi, l'ottimizzazione dei workflow documentali e la digitalizzazione dei processi.