Integrare la firma elettronica in 20 minuti
Scopri come integrare un'API di firma elettronica in meno di 20 minuti: creazione di una richiesta, invio del link, ricezione del webhook firmato e recupero del PDF firmato.
Integrare la firma elettronica nella vostra applicazione non richiede settimane di sviluppo. Con un'API ben progettata, potete offrire la firma in pochi minuti. Questo tutorial vi mostra passo dopo passo come creare una richiesta di firma, trasmettere il link al firmatario, ricevere una notifica firmata e recuperare il documento firmato, utilizzando Sign-Hub. Affronteremo inoltre gli aspetti di sicurezza e conformità essenziali.
Perché integrare la firma elettronica?
La firma elettronica è diventata uno standard per contratti, preventivi o qualsiasi documento che necessiti di una validazione. Integrarla nella vostra applicazione evita i passaggi di stampa, scansione e invio postale. Per uno sviluppatore, ciò significa automatizzare un processo aziendale e offrire un'esperienza fluida all'utente finale.
Panoramica dell'API Sign-Hub
Sign-Hub è un servizio di firma elettronica edito da NEW VISION OF APPS (SAS, Janzé, Francia). Si posiziona come una soluzione API-first: l'insieme delle funzionalità è accessibile tramite un'API REST. Una sola rotta permette di creare una richiesta di firma. Il servizio gestisce poi l'invio delle email, il monitoraggio delle firme e la generazione dei documenti probatori.
L'API è documentata secondo la specifica OpenAPI 3.1. Un SDK TypeScript è disponibile per facilitare l'integrazione. Inoltre, un file llms.txt è progettato per essere letto da un assistente di codice, il che accelera lo sviluppo.
Prerequisiti
- Un account Sign-Hub (offerta Découverte gratuita, 10 atti al mese)
- Una chiave API (disponibile nella dashboard)
- Un ambiente di sviluppo (Node.js per questo tutorial)
Passo 1: Creare una richiesta di firma
Il primo passo consiste nel chiamare l'API per creare una richiesta. Dovete fornire il documento da firmare (PDF), l'identificativo del firmatario (email, nome) ed eventualmente opzioni come l'ordine di firma.
Esempio di richiesta con curl:
curl -X POST "https://api.sign-hub.example.com/v1/signature-requests" \
-H "Authorization: Bearer VOTRE_CLE_API" \
-H "Content-Type: application/json" \
-d '{
"document": {"name": "contrat.pdf", "content": "base64..."},
"signers": [
{"email": "client@example.com", "first_name": "Jean", "last_name": "Dupont"}
]
}'
La risposta contiene un identificativo di richiesta e un link pubblico di firma. Questo link è unico per ogni firmatario. Potete trasmetterlo via email o visualizzarlo nella vostra interfaccia.
Passo 2: Trasmettere il link al firmatario
Il link pubblico può essere integrato in un'email automatica o visualizzato in una pagina della vostra applicazione. Sign-Hub gestisce anche l'invio di email di sollecito se lo configurate. Nel nostro esempio, inviamo il link direttamente tramite l'API di vostra scelta.
Passo 3: Ricevere il webhook firmato
Quando il firmatario ha terminato la sua firma, Sign-Hub invia una notifica al vostro server tramite un webhook. Questo webhook è firmato con un segreto HMAC per garantirne l'autenticità. Sono proposte due versioni: una semplice e una con marca temporale anti-replay.
Per verificare il webhook, dovete calcolare la firma HMAC a partire dal corpo della richiesta e confrontarla con l'header fornito. In caso di fallimento, ignorate la richiesta.
Esempio di verifica in Node.js:
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return expected === signature;
}
Passo 4: Recuperare il PDF firmato e il dossier di prova
Dopo il webhook, potete recuperare il PDF firmato e il dossier di prova tramite l'API. Il PDF è sigillato nel formato PAdES, garantendone l'integrità. Il dossier di prova contiene tutte le informazioni necessarie per verificare la validità della firma.
Esempio di recupero:
curl -X GET "https://api.sign-hub.example.com/v1/signature-requests/{id}/signed-pdf" \
-H "Authorization: Bearer VOTRE_CLE_API"
La prova verificabile: un vantaggio distintivo
A differenza di molti attori, Sign-Hub permette a chiunque di verificare la validità di una firma senza fidarsi dell'editore. Il dossier di prova è firmato con una chiave Ed25519, la cui chiave pubblica è pubblicata a un indirizzo ben noto. Potete verificare un proof.json offline o tramite uno strumento online. Questa trasparenza rafforza il valore probatorio.
Sicurezza e conformità
Sign-Hub rispetta il regolamento eIDAS (regolamento (UE) n. 910/2014) per la firma elettronica semplice. Il consenso del firmatario è esplicitamente registrato, l'impronta del documento è fissata al momento della firma, e i dati di connessione sono anonimizzati in conformità al RGPD, senza compromettere la prova. I dati sono ospitati nell'Unione europea.
È importante notare che la firma proposta è una firma elettronica semplice, rafforzata dalla verifica dell'email e dalla sigillatura. Non costituisce una firma avanzata o qualificata ai sensi di eIDAS. Per atti in cui la legge richiede una firma qualificata, possono essere necessarie altre soluzioni come Universign.
Confronto con altre soluzioni
Yousign, DocuSign e Universign offrono anch'essi API di firma elettronica. La maggior parte propone funzionalità simili: invio di link, monitoraggio, webhook. Sign-Hub si distingue per la sua trasparenza sulla verifica della prova e per il suo approccio API-first con una documentazione pensata per l'IA. Il suo prezzo a consumo, senza abbonamento obbligatorio, può essere adatto alle piccole strutture.
Per approfondire
L'SDK TypeScript permette di integrare rapidamente l'API nei vostri progetti. La specifica OpenAPI 3.1 è disponibile, e il file llms.txt può essere utilizzato da assistenti di codice per generare codice di integrazione. Per testare, create un account sull'offerta Découverte e utilizzate la vostra prima chiave API.
Conclusione
Integrare la firma elettronica nella vostra applicazione è alla portata di ogni sviluppatore, e Sign-Hub lo rende semplice e rapido. In meno di 20 minuti, potete creare una richiesta, ricevere il webhook e recuperare il documento firmato. La documentazione completa e gli strumenti forniti vi permetteranno di andare oltre secondo le vostre esigenze.