Guida alla Migrazione Firma_Elettronica a EU-SES

Ecco una guida passo-passo per migrare dalla vecchia API Firma Digitale alla nuova API eSignature. Tieni presente che la vecchia API è stata deprecata e il suo supporto terminerà il 31 dicembre 2026.

1. Modifica dei Domini Base (Base URL)

Il primo passo per la migrazione è aggiornare i domini delle tue chiamate API per puntare ai nuovi server di eSignature:

• Produzione: passa da https://ws.firmadigitale.com a https://esignature.openapi.com.
• Sandbox: passa da https://test.ws.firmadigitale.com a https://test.esignature.openapi.com.

2. Mappatura degli Endpoint

I vecchi endpoint /firma_elettronica sono stati sostituiti e riorganizzati all'interno della nuova API eSignature, introducendo la differenziazione tra l'endpoint di creazione della firma /EU-SES e quello per accedere all’elenco storico delle firme /signatures e i dettagli di un singolo documento firmato /signatures/{id}/{actionType}.

Ecco la mappatura esatta per la migrazione:

Creazione della richiesta di firma elettronica semplice (SES)

Recupero dell'elenco delle firme / richieste

Ottenere le informazioni / dettagli su una richiesta specifica

Scaricamento del documento firmato

Recupero dell'Audit Trail (traccia di controllo)

Cancellazione dei documenti (Nuova funzionalità)

3. Modifica modalità di personalizzazione UI

Nella vecchia API c'erano degli endpoint dedicati alla creazione e gestione di interfacce grafiche personalizzate (/firma_elettronica_ui) per l'iframe di firma. Questi endpoint (POST, GET e DELETE /firma_elettronica_ui) sono stati già contrassegnati come DEPRECATO.

Nella nuova API sono stati superati tutti i limiti della precedente e potranno essere create illimitate interfacce direttamente in fase di richiesta POST /EU-SES passando tutte le informazioni di personalizzazione nei campi previsti nelle opzioni.

Queste sono le opzioni opzionali per personalizzare l'interfaccia utente visibile all'utente finale o la modalità di firma:

1. Colori e Stile (Tematizzazione)

Tutti i parametri di colore richiedono una stringa in formato esadecimale (HEX) che segua il pattern: ^#[0-9a-fA-F]{6}$.

Area Barra Laterale (Sidebar)

Area Intestazione e Piè di Pagina (Header & Footer)

Pulsanti Standard

Pulsanti di Firma / Procedura (Sign Button)

2. Visibilità e Comportamento

Questi parametri controllano la visualizzazione degli elementi dell'interfaccia. Il valore predefinito è false per tutti i campi booleani.

3. Integrazione e Reindirizzamento

Parametri utilizzati per gestire l'incorporamento dell'applicazione e il flusso di navigazione post-operazione.

4. Conservazione dei documenti nella nuova API

Un aspetto importante della nuova API di cui tenere conto durante la migrazione è la policy di retention. Nella nuova API eSignature:

• I documenti firmati, validati e caricati rimarranno disponibili per il download nel sistema per un massimo di 90 giorni, dopodiché verranno automaticamente cancellati.
• I dati strutturati della firma e l'audit trail saranno conservati per un massimo di 10 anni.

Assicurati che i tuoi processi di backend siano aggiornati per scaricare il file finale da /signatures/{id}/signedDocument e archiviarlo sui tuoi sistemi entro la finestra temporale di 90 giorni.

5. Differenze body della chiamata (POST)

Il payload della richiesta di creazione di una nuova firma (POST /EU-SES) ha subito modifiche significative rispetto al vecchio endpoint POST /firma_elettronica/base.

Vecchio Body della Chiamata (Esempio)

{
  "members": [
    {
      "firstname": "Mario",
      "lastname": "Rossi",
      "email": "[email protected]",
      "phone": "+393333333333",
      "signs": [
        {
          "page": 1,
          "position": "100,200,45,35"
        }
      ]
    }
  ],
  "callback": {
    "headers": {
      "custom": "test"
    },
    "field": "data",
    "url": "https://webhook.site/12345678"
  },
  "content": "JVBERi0xLjQNCiWio4+TD..."
}

Nuovo Body della Chiamata (Esempio)

{
  "signers": [
    {
      "name": "Mario",
      "surname": "Rossi",
      "email": "[email protected]",
      "mobile": "+393333333333",
      "message": "Ciao Mario, {OTP} è il codice da inserire...",
      "authentication": [
        "sms"
      ],
      "signatures": [{
        "page": 1,
        "x": "100",
        "y": "200"
      }]
    }
  ],
  "options": {
    "signatureMode": [
      "drawn"
    ],
    "ui": {
      "sidebarLogo": "https://www.tua-azienda.com/logo.png",
      "buttonBackgroundColor": "#0a5aa6"
    }
  },
  "inputDocuments": {
    "sourceType": "base64",
    "payload": "JVBERi0xLjQK..."
  },
  "callback": {
    "url": "https://webhook.site/12345678"
  }
}

Mappatura e Punti Chiave di Migrazione del Payload

Dettagli del Nuovo Oggetto di Callback

L'oggetto callback (inviato nella richiesta POST /EU-SES) definisce la configurazione del webhook che la piattaforma eSignature utilizzerà per notificare l'applicazione esterna sui cambi di stato della richiesta di firma.

Di seguito sono descritti i campi supportati nella configurazione del callback:

Esempio di Configurazione Completa:

{
    "callback": {
        "url": "https://www.tuosito.com/api/webhook/firma",
        "method": "JSON",
        "field": "data",
        "retry": 3,
        "headers": {
            "Authorization": "Bearer tuo_token_di_sicurezza",
            "X-Custom-Header": "valore_personalizzato"
        },
        "custom": {
            "id_pratica_interna": "PRT-98765",
            "dipartimento": "Risorse Umane"
        }
    }
}

6. Body di risposta della nuova firma

Il body di risposta della chiamata:

POST /EU-SES

è stato arricchito nella nuova API eSignature per fornire immediatamente non solo l'ID univoco della richiesta creata e l'URL di reindirizzamento per l'interfaccia di firma, ma anche lo stato aggiornato dell'intera richiesta, l'ID dell'utente firmatario, e l'URL specifico per l'accesso del firmatario.
Di seguito un esempio del body di risposta esteso previsto:

{
    "data": {
        "id": "69aaa647adb8b5c802035539",
        "errorNumber": null,
        "errorMessage": null,
        "updatedAt": "2026-03-06 10:02:47.980+00:00",
        "createdAt": "2026-03-06 10:02:47.979+00:00",
        "certificateType": "EU-SES",
        "state": "WAIT_VALIDATION",
        "signatureType": "pades",
        "signers": [
            {
                "authentication": [
                "sms"
                ],
                "name": "Mario",
                "state": "NEW",
                "surname": "Rossi",
                "mobile": "+393333333333",
                "mobileEditable": false,
                "email": "[email protected]",
                "emailEditable": false,
                "id": "b99f85d9-8482-4970-b57d-ff6703a98818",
                "url":"https://esign.openapi.com/b99f85d9-8482-4970-b57d-ff6703a98818",
                "language": "browser",
                "message": "Ciao Mario, {OTP} è il codice da inserire per confermare la procedura di firma",
                "mobileValidation": {
                    "isPossible": true,
                    "isValid": true,
                    "regionCode": "IT",
                    "countryCode": "39",
                    "isValidNumberForRegion": true,
                    "numberType": "MOBILE",
                    "otpAttempts": 0
                }
            }
        ],
        "options": {
        "asyncDocumentsValidation": true,
        "asyncSignature": false,
        "signatureMode": [
        "typed"
        ],
        "withTimestamp": false,
        "timezone": "UTC"
    },
    "document": {}
}}

Dettagli del Body di Callback di Risposta (Esempio Stato DONE)

L'esempio fornito è un tipico body di callback inviato dalla nuova API eSignature quando lo stato di una richiesta di firma passa a un punto significativo, in questo caso, DONE.

Analisi dei Dettagli Chiave

Dettagli del Firmatario (signers Array)

Documenti (Sezione document)

In uno stato DONE, vengono fornite informazioni dettagliate sia sul documento originale validato che sul documento firmato:

Azione Raccomandata:

Dato che lo stato è DONE e il campo signedDocument è presente, il passo successivo nel tuo sistema dovrebbe essere quello di utilizzare l'ID principale (69aaada4adb8b5c80203553d) per effettuare una chiamata GET /signatures/{id}/signedDocument e scaricare il file firmato. Ricorda che il documento è conservato solo per 90 giorni.