Report firma elettronica: riferimento a signatures[]

Ogni passaggio di Firma elettronica produce un risultato per firmatario. Lo trovi come elemento di signatures[] in:

GET /v3/session/{sessionId}/decision/, per le sessioni di Verifica degli utenti (KYC) e Verifica aziendale (KYB).
La decision dei webhook di sessione V3, inviati quando la sessione è Approved, Declined, In Review o Abandoned.
La scheda Firma della sessione nella console e la sezione della firma del report PDF.

signatures è presente nella decisione solo quando il workflow contiene un passaggio di Firma elettronica. È un array vuoto finché un firmatario non raggiunge il passaggio. Un passaggio KYC ha un elemento; un passaggio KYB ha un elemento per firmatario.

Esempio

{
  "signatures": [
    {
      "id": "0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10",
      "node_id": "feature_signature",
      "status": "signed",
      "verdict": "Approved",
      "level": "aes",
      "format": "pades",
      "profile": "PAdES-B-LT",
      "signer": {
        "name": "Jane Doe",
        "capacity": "self",
        "company": null,
        "role": null,
        "roles": [],
        "identity_session_id": "11111111-2222-3333-4444-555555555555"
      },
      "identity_used": {
        "session_id": "11111111-2222-3333-4444-555555555555",
        "kyc_id": "6f1e8f6c-1d2b-4c3a-9e8f-7a6b5c4d3e2f",
        "verified": true,
        "expected_name": "Jane Doe"
      },
      "certificate": {
        "issuer": "<certificate issuer>",
        "issued_to": "<certificate subject>",
        "serial": "5A3F9C21",
        "valid_from": "2026-01-01T00:00:00+00:00",
        "valid_until": "2028-01-01T00:00:00+00:00"
      },
      "confirmation": {
        "channel": "email",
        "destination": "j***@example.com",
        "confirmed_at": "2026-11-03T10:42:18.512Z",
        "attempts": 1
      },
      "timestamp": {
        "time": "2026-11-03T10:42:21+00:00",
        "qualified": false,
        "valid": true
      },
      "documents": [
        {
          "id": "9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b",
          "uuid": "9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b",
          "title": "Account agreement",
          "file_name": "agreement.pdf",
          "pages": 4,
          "size_bytes": 182344,
          "sha256_original": "3b8e5f0c2a9d4e7f1b6c0a5d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f",
          "sha256_signed": "a1f2e3d4c5b6a7980f1e2d3c4b5a69788f7e6d5c4b3a29180f1e2d3c4b5a6978",
          "status": "signed",
          "opened_at": "2026-11-03T10:40:02.118Z",
          "read_at": "2026-11-03T10:41:10.044Z",
          "read_to_end": true,
          "consented_at": "2026-11-03T10:41:12.730Z",
          "consent": true,
          "signed_file": "/v3/session/11111111-2222-3333-4444-555555555555/signatures/feature_signature/documents/9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b/file/",
          "mode": "fields",
          "source_format": "pdf",
          "conversion": null,
          "fields": [
            {
              "key": "full_name",
              "type": "full_name",
              "role": "verified_person",
              "label": "Full name",
              "page": 1,
              "x": 0.34,
              "y": 0.2326,
              "width": 0.57,
              "height": 0.0325,
              "required": true,
              "value": "Jane Doe",
              "display_value": "Jane Doe",
              "value_source": "identity",
              "filled_at": "2026-11-03T10:40:02.118Z",
              "value_unavailable_reason": null
            },
            {
              "key": "occupation",
              "type": "text",
              "role": "verified_person",
              "label": "Occupation",
              "page": 1,
              "x": 0.34,
              "y": 0.4618,
              "width": 0.57,
              "height": 0.0325,
              "required": true,
              "value": "Architect",
              "display_value": "Architect",
              "value_source": "signer",
              "filled_at": "2026-11-03T10:40:41.502Z",
              "value_unavailable_reason": null
            },
            {
              "key": "signature",
              "type": "signature",
              "role": "verified_person",
              "label": "Signature",
              "page": 4,
              "x": 0.09,
              "y": 0.5303,
              "width": 0.36,
              "height": 0.0849,
              "required": true,
              "value": true,
              "display_value": "Signed",
              "value_source": "signer",
              "filled_at": "2026-11-03T10:41:05.200Z",
              "image_url": "/v3/session/11111111-2222-3333-4444-555555555555/signatures/feature_signature/fields/c4d5e6f7-0a1b-4c2d-8e3f-4a5b6c7d8e9f/image/",
              "value_unavailable_reason": null
            }
          ]
        }
      ],
      "adopted_signature": {
        "method": "drawn",
        "font": null,
        "adopted_at": "2026-11-03T10:41:02.871Z"
      },
      "electronic_signature_consent_at": "2026-11-03T10:41:40.016Z",
      "evidence_file": "/v3/session/11111111-2222-3333-4444-555555555555/signatures/feature_signature/evidence/?signature_id=0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10",
      "warnings": [],
      "validation": {
        "valid": true,
        "checked_at": "2026-11-03T10:42:24.903Z",
        "documents": [
          {
            "id": "9b0a7f44-2c1d-4e5f-8a9b-0c1d2e3f4a5b",
            "checked_at": "2026-11-03T10:42:24.903Z",
            "valid": true,
            "integrity": true,
            "trusted": true,
            "revoked": false,
            "trusted_list": { "status": "not_applicable", "reason": "aes_not_qualified" },
            "certificate": {
              "issuer": "<certificate issuer>",
              "issued_to": "<certificate subject>",
              "serial": "5A3F9C21",
              "valid_from": "2026-01-01T00:00:00+00:00",
              "valid_until": "2028-01-01T00:00:00+00:00"
            },
            "timestamp": { "time": "2026-11-03T10:42:21+00:00", "qualified": false, "valid": true }
          }
        ]
      },
      "declined_at": null,
      "declined_action": "REVIEW",
      "signed_at": "2026-11-03T10:42:24.903Z",
      "expires_at": "2026-11-10T10:30:00.000Z",
      "email_sent_at": "2026-11-03T10:42:30.011Z",
      "email_unavailable_reason": null,
      "ip_address": "203.0.113.10",
      "place": null,
      "place_unavailable_reason": "not_collected"
    }
  ]
}

L’oggetto della firma

Campo	Tipo	Descrizione
`id`	string (UUID)	La firma del firmatario. Passalo come `signature_id` per scaricare le sue prove o convalidare la sua firma.
`node_id`	string	Il passaggio del workflow che lo ha generato.
`status`	string	La fase in cui si trova il firmatario nel passaggio: `intro`, `review`, `code`, `signing`, `signed` o `declined`. Solo `signed` indica che i documenti sono firmati.
`verdict`	string	L’esito del passaggio: `Not Finished`, `Approved`, `In Review` o `Declined`. Una firma rifiutata o non riuscita assume l’esito della sua regola, e le regole di stato personalizzate possono modificarlo.
`level`	string	`simple` (predefinito) o `aes`. `qes` è un componente aggiuntivo non ancora disponibile.
`format`	string	`pdf` per una firma Semplice, `pades` per l’Avanzata (AES).
`profile`	string \| null	`PAdES-B-LT` una volta firmata una firma Avanzata (AES), altrimenti `null`.
`signer`	object	Chi ha firmato. Consulta Firmatario.
`identity_used`	object	L’identità verificata su cui si basa la firma. Consulta Firmatario. Vuoto per una firma Semplice senza identità verificata.
`certificate`	object \| null	Il certificato con cui sono stati firmati i documenti: `issuer`, `issued_to`, `serial`, `valid_from` e `valid_until`. `null` finché non viene firmato, e sempre `null` per una firma Semplice.
`confirmation`	object	Il codice monouso: `channel` (`email` o `sms`), `destination` (il recapito oscurato a cui è stato inviato), `confirmed_at` e `attempts` (codici inseriti, compreso quello corretto). Una firma Semplice non prevede codice, quindi `channel` e `destination` sono `null`.
`timestamp`	object \| null	La marca temporale RFC 3161 nella firma, emessa da Didit: `time`, `qualified` (sempre `false` per AES) e `valid`. `null` finché non viene firmato, e sempre `null` per una firma Semplice.
`documents`	array	Un elemento per ciascun documento. Consulta Documenti.
`adopted_signature`	object \| null	La firma e le sigle adottate dal firmatario per i campi di firma e sigla: `method` (`typed` o `drawn`), `font` (lo stile calligrafico di una firma digitata, oppure `null` se disegnata) e `adopted_at`. `null` finché il firmatario non ne adotta una.
`electronic_signature_consent_at`	string \| null	Quando il firmatario ha acconsentito, nella schermata di revisione, a firmare elettronicamente i documenti. Impostato quando almeno un documento contiene campi.
`evidence_file`	string \| null	Percorso del PDF probatorio di questo firmatario, una volta firmato.
`warnings`	array	Elementi `{ "code", "node_id" }` per ciascun avviso generato.
`validation`	object \| null	L’ultima verifica crittografica dei documenti firmati. Consulta Rivalidare una firma.
`declined_at`	string \| null	Quando il firmatario ha rifiutato.
`declined_action`	string	Il parametro `signature_declined_action` del passaggio: cosa comporta un rifiuto per l’esito.
`signed_at`	string \| null	Quando sono stati firmati i documenti.
`expires_at`	string	Quando il link per la firma smette di funzionare.
`email_sent_at`	string \| null	Quando Didit ha inviato via email una copia firmata al firmatario.
`email_unavailable_reason`	string \| null	Il motivo per cui non è stata inviata alcuna copia via email, se ne era stata richiesta una.
`ip_address`	string \| null	L’indirizzo IP del firmatario al momento della richiesta del codice.
`place`	string \| null	Non raccolto. Sempre `null`, con `place_unavailable_reason: "not_collected"`.

Non considerare mai che un firmatario abbia firmato finché status non è signed. In una firma Avanzata (AES), un valore null per certificato, timestamp o signed_file indica che non è ancora presente alcuna firma. Una firma Semplice firmata contiene un signed_file, ma presenta sempre certificato e timestamp impostati su null.

Firmatario

Campo	Descrizione
`signer.name`	Il nome verificato del firmatario, ricavato dalla sua verifica dell’identità approvata. Al livello Semplice è il nome verificato della sessione, se presente, altrimenti il nome digitato dal firmatario, che non è verificato.
`signer.capacity`	`self` quando una persona firma per se stessa (KYC), `company` quando una persona chiave firma per conto di un’azienda (KYB).
`signer.company`	La denominazione dell’azienda, per KYB.
`signer.role`	La qualifica della persona chiave, come dichiarata, per KYB.
`signer.roles`	I ruoli strutturati della persona chiave, come `representative` o `authorized_signatory`, che la qualificano come firmatario. Si tratta dei ruoli dichiarati per l’azienda, non di una conferma dal registro delle imprese.
`signer.identity_session_id`	La sessione KYC che ha verificato il firmatario. Per KYB, la sessione KYC della persona chiave stessa. Assente per una firma Semplice senza identità verificata.
`identity_used.session_id`	Uguale a `signer.identity_session_id`. `identity_used` è vuoto per una firma Semplice senza identità verificata, quindi nessuno dei suoi campi è presente.
`identity_used.kyc_id`	La verifica dell’identità da cui proviene il nome.
`identity_used.verified`	`true` quando la verifica dell’identità è stata approvata.
`identity_used.expected_name`	Il nome a cui il firmatario doveva corrispondere. Per KYB, il nome dichiarato per la persona chiave.

Documenti

Campo	Descrizione
`id`, `uuid`	Il documento. Usalo per scaricare il file firmato.
`title`, `file_name`	Come caricato o inviato.
`pages`, `size_bytes`	Del documento firmato dal firmatario. Per i file Word, del PDF convertito.
`sha256_original`	SHA-256 del documento così come è stato mostrato al firmatario.
`sha256_signed`	SHA-256 del PDF firmato, una volta firmato.
`status`	`signed`; `declined`; `not_signed` (aperto, non firmato); o `not_reached` (mai aperto).
`opened_at`	Quando il firmatario lo ha aperto per la prima volta.
`read_at`, `read_to_end`	Quando il firmatario ha raggiunto la fine di un documento senza campi, se richiedi la lettura fino alla fine. Un documento con campi non lo richiede.
`consented_at`, `consent`	Quando il firmatario ha accettato un documento senza campi, se richiedi il consenso per ciascun documento, oppure ha completato i campi di un documento che li contiene.
`signed_file`	Percorso del PDF firmato, una volta firmato.
`mode`	`fields` per un documento con campi, `read_and_agree` per un documento senza campi.
`source_format`	`pdf`, o `docx` per un documento Word convertito da Didit.
`conversion`	`null` per un PDF. Per un documento Word, `{ "from": "docx", "file_name", "sha256", "size_bytes", "converter" }`: il tuo file originale, il suo SHA-256 e le dimensioni, e la versione del convertitore.
`fields`	I campi del documento, con i relativi valori. Vuoto per un documento senza campi.

Campi

Ciascun elemento di documents[].fields[] è un campo del documento, con il relativo valore sulla copia di questo firmatario:

Campo	Descrizione
`key`	La chiave del campo, la stessa che usi in `sign.field_values`.
`type`, `role`, `label`, `required`	Come posizionati sul documento.
`page`, `x`, `y`, `width`, `height`	La posizione del campo, come frazioni della pagina così come viene visualizzata.
`value`	Una stringa per i campi `text`, `email`, `full_name`, `date_signed` e `data`, un booleano per una casella di controllo e `true` per una firma o delle iniziali applicate. `null` quando il campo è vuoto.
`display_value`	Il valore così come viene apposto sulla pagina: date nel `date_format` del campo, `Yes` o `No` per una casella di controllo e `Signed` per una firma o iniziali.
`value_source`	L’origine del valore: `signer` (digitato, selezionato o applicato dal firmatario), `identity` (il documento d’identità verificato), `contact` (l’email o il telefono verificati), `company` (l’azienda verificata), `session` (`vendor_data` della sessione), `metadata` (`metadata` della sessione), `api` (i tuoi `sign.field_values`) o `signing_time` (la data della firma).
`filled_at`	Quando è stato impostato il valore.
`image_url`	Per una firma o le iniziali, il percorso dell’immagine applicata, in formato PNG. Vedi Scarica un’immagine della firma.
`value_unavailable_reason`	Il motivo per cui un campo compilato da Didit non ha alcun valore: `not_verified` (l’identità o il contatto non sono stati verificati), `not_applicable` (un campo aziendale sulla firma personale di un individuo), `not_provided` (la sorgente non ha alcun valore) o `set_at_confirmation` (una data di firma precedente alla conferma del firmatario). Altrimenti `null`.

Scarica i documenti firmati

Usa i percorsi in signed_file ed evidence_file con la tua chiave API. Ciascun endpoint restituisce il PDF stesso.

# Signed PDF of one document
curl -L 'https://verification.didit.me/v3/session/{session_id}/signatures/{node_id}/documents/{document_id}/file/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -o agreement-signed.pdf

# Evidence PDF of one signer
curl -L 'https://verification.didit.me/v3/session/{session_id}/signatures/{node_id}/evidence/?signature_id={signature_id}' \
  -H 'x-api-key: YOUR_API_KEY' \
  -o signature-evidence.pdf

Percorso	Riferimento
`GET .../documents/{document_id}/file/`	Scarica un documento firmato
`GET .../evidence/`	Scarica il documento probatorio della firma
`GET .../fields/{field_id}/image/`	Scarica un’immagine della firma
`POST .../validate/`	Valida le firme

Prima di rispondere, Didit confronta il file memorizzato con il relativo SHA-256 registrato. Se differiscono, le route per il PDF firmato e il file probatorio restituiscono 409 e la route per l’immagine restituisce 400, ciascuna con signature_document_changed. Passa sempre signature_id alla route del file probatorio quando un passaggio KYB ha più firmatari.

Il PDF firmato

Il PDF firmato contiene, nell’ordine:

Le pagine del documento mostrato al firmatario, con ciascun valore del campo impresso nel punto in cui hai posizionato il campo.
La pagina probatoria, a meno che tu non abbia disattivato signature_evidence_page.
Solo per Advanced (AES), la firma PAdES, con la marca temporale RFC 3161 emessa da Didit e i dati di revoca necessari per convalidarla in futuro. Un PDF Simple termina dopo la pagina probatoria e non ha firma digitale, sigillo o marca temporale.

In un PDF Advanced (AES), la firma copre ogni singolo byte precedente, inclusi i valori dei campi e la pagina probatoria. Modificare qualsiasi elemento del file successivamente invalida la firma, e qualsiasi validatore compatibile con PAdES lo evidenzia. I dettagli della firma indicano il firmatario e fanno riferimento alla sua sessione di verifica dell’identità e alla conferma tramite codice. I valori dei campi diventano parte del contenuto della pagina, non campi modulo, quindi non possono essere modificati successivamente e ogni visualizzatore PDF li mostra. Una casella di controllo spuntata mostra un segno di spunta, mentre una non spuntata viene lasciata così come è stata disegnata nel documento. Un riquadro della firma più alto di 24 punti riceve anche una piccola didascalia sotto la firma: Signed with Didit · seguito dai primi 8 caratteri dell’id della firma. Didit aggiunge i valori dei campi, la pagina probatoria e la firma dopo i byte del documento mostrato al firmatario. Quel documento è un prefisso esatto del file firmato, per cui sha256_original può ancora essere verificato rispetto al PDF firmato.

Il PDF probatorio

Il PDF probatorio registra, per un firmatario:

Il livello e il formato.
Il nome del firmatario, il titolo in base al quale firma e, per il KYB, l’azienda.
La sessione di verifica dell’identità (solo Advanced (AES)).
La conferma: canale, destinazione mascherata e orario (solo Advanced (AES)).
L’indirizzo IP del firmatario.
Ciascun documento: titolo, numero di pagine e SHA-256 dell’originale. Per un documento Word, il nome del file Word e il relativo SHA-256, la versione del convertitore e lo SHA-256 del PDF.
La firma adottata: digitata (con il relativo stile calligrafico) o disegnata, la data e l’ora di adozione, nonché le immagini della firma e delle iniziali.
Ciascun campo, per documento: la relativa etichetta, pagina e tipo, il suo valore (l’immagine per una firma o per le iniziali), l’origine del valore (ad esempio Digitato dal firmatario, Documento d’identità verificato o La tua API), quando è stato compilato (UTC) e, per un valore digitato dal firmatario, il suo indirizzo IP in quel momento.
Il consenso finale: il testo accettato dal firmatario nella schermata di revisione e la data e ora.
Lo SHA-256 di ogni file firmato e, per Advanced (AES), il certificato (rilasciato a, emittente, numero di serie e validità) e la marca temporale.

La pagina aggiunta a ciascun PDF firmato presenta lo stesso contenuto senza la sezione del certificato, poiché viene inserita prima che la firma venga applicata.

Convalida nuovamente una firma

POST /v3/session/{session_id}/signatures/{node_id}/validate/ rilegge ogni PDF firmato del passaggio e ne verifica lo SHA-256. Per una firma avanzata (AES) convalida anche la firma PAdES, il relativo certificato, i dati di revoca e il timestamp. Una firma semplice non include una firma digitale, quindi il controllo riguarda solo l’integrità del file. Salva il risultato in validation e restituisce signatures[] aggiornato. Invia signature_id per controllare un singolo firmatario. Richiede write:sessions, e nella console corrisponde al pulsante Convalida di nuovo. Un PDF firmato archiviato che non corrisponde più al proprio sha256_signed restituisce 400 con signature_document_changed. Finché i documenti non vengono firmati, validation è null. Se Didit non riesce a confermare l’esito della firma, validation è { "valid": null, "reason": "signature_provider_outcome_unknown", "checked_at" } e status rimane signing fino alla risoluzione: trattalo come non firmato.

Campo di `validation.documents[]`	Descrizione
`valid`	`true` quando sia la firma sia il timestamp sono validi e attendibili. Per una firma semplice, `true` quando il file non è stato modificato.
`integrity`	`true` quando il documento non è stato modificato dopo la firma.
`trusted`	`true` quando la catena del certificato di firma risale a una radice attendibile. `null` per una firma semplice.
`revoked`	`true` quando il certificato di firma è stato revocato. `null` per una firma semplice.
`trusted_list`	`{ "status": "not_applicable", "reason": "aes_not_qualified" }` per AES. Il controllo della lista di fiducia dell’UE si applica alle firme qualificate. Una firma semplice restituisce `{ "status": "not_applicable", "reason": "simple_not_sealed" }`.
`certificate`, `timestamp`	Come rilevati nel file.

Nel report PDF

Il report PDF stampa una sezione relativa alla firma con il firmatario, la conferma, il certificato, il timestamp e i documenti con i relativi hash. Quando i documenti contengono campi, segue una pagina Firma elettronica · campi, con una tabella per documento: il valore di ogni campo, le immagini della firma e delle sigle, gli orari e le origini. La sezione relativa alla firma compare dopo Verifica bancaria in un report KYC e dopo Documenti in un report KYB. Passa pages=signature per stampare solo quella sezione.

Autenticazione

Verifica

Monitoraggio

Piattaforma

Report firma elettronica: riferimento a signatures[]

Esempio

L’oggetto della firma

Firmatario

Documenti

Campi

Scarica i documenti firmati

Il PDF firmato

Il PDF probatorio

Convalida nuovamente una firma

Nel report PDF

Correlati

​Esempio

​L’oggetto della firma

​Firmatario

​Documenti

​Campi

​Scarica i documenti firmati

​Il PDF firmato

​Il PDF probatorio

​Convalida nuovamente una firma

​Nel report PDF

​Correlati

Esempio

L’oggetto della firma

Firmatario

Documenti

Campi

Scarica i documenti firmati

Il PDF firmato

Il PDF probatorio

Convalida nuovamente una firma

Nel report PDF

Correlati