Firma Elettronica Qualificata Automatica

La soluzione di Firma Elettronica Qualificata (QES) automatica consente di semplificare i processi di firma, garantendo la piena conformità alle normative europee.

È un servizio API estremamente flessibile, che può essere personalizzato in base alle esigenze dei singoli. Ci sono varie opzioni disponibili: è possibile sottoscrivere documenti in modalità singola o massiva direttamente da server, selezionare qualsiasi formato di firma (CAdES, PAdES, XAdES e PKCS#1), impostare se la validazione del documento e se la firma debbano essere sincroni o asincroni.

Non sono previsti canoni annuali: si paga solo per il costo di attivazione del certificato e gli utilizzi effettivi.

La Firma QES è disponibile anche per persone giuridiche, attraverso un servizio apposito (Sigillo Elettronico Qualificato).

L'implementazione della firma elettronica tramite API consente di offrire ai propri dipendenti o utenti un'esperienza semplificata di firma da remoto di qualsiasi documento, garantendo allo stesso tempo sicurezza e validità europea. La firma elettronica è infatti riconosciuta dalla legge dell’Unione Europea tramite la regolamentazione eIDAS. 

La soluzione dispone di 30 livelli di sicurezza customizzabili e può essere integrata tramite API in gestionali, software e siti web, per rendere più immediata e sicura la firma di ordini, preventivi, richieste di attivazione, contratti.

Prima di iniziare ad utilizzare la Firma QES è necessario acquistare un certificato di firma tramite l'endpoint dedicato POST /certificates/namirial-automatic.

Una volta attivato il certificato, sarà possibile iniziare ad utilizzare il servizio specifico di firma automatica. È disponibile sia il servizio "automatico" che il servizio con "OTP", cioè l'autenticazione forte grazie all'utilizzo delle One Time Password, che consente di aumentare il livello di sicurezza della firma e proteggere ulteriormente i documenti firmati (endpoint di riferimento: EU-QES_otp).

Richiesta di Firma Elettronica Qualificata (EU-QES_automatic)

POST/EU-QES_automatic

L'endpoint POST/EU-QES_automatic permette 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 anticipato, il servizio è estremamente flessibile e consente - tramite le 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).

Il servizio consente inoltre di procedere alla marcatura del documento con qualsiasi tipologia di marca temporale.

Risposta di Firma Elettronica Qualificata (EU-QES_automatic)

POST/EU-QES_automatic

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}

Alla fine della procedura di firma sarà possibile richiedere il dettaglio del processo di firma completato, 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 consente anche 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 è stata già integrata per la firma di documenti come pre-contratti, preventivi, contratti di vendita o noleggi e generici.