> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Report firma elettronica: riferimento a signatures[]

> Consulta signatures[] nelle decisioni e nei webhook Didit, scarica i PDF firmati e di evidenza e valida nuovamente una firma.

Ogni passaggio di [Firma elettronica](https://docs.didit.me/it/core-technology/electronic-signature/overview.md) produce un risultato per firmatario. Lo trovi come elemento di `signatures[]` in:

* [`GET /v3/session/{sessionId}/decision/`](https://docs.didit.me/it/sessions-api/retrieve-session), per le sessioni di Verifica degli utenti (KYC) e Verifica aziendale (KYB).
* La `decision` dei [webhook di sessione](https://docs.didit.me/it/integration/webhooks.md) 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](https://docs.didit.me/it/sessions-api/generate-pdf.md).

`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

```json theme={null}
{
  "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](https://docs.didit.me/it/core-technology/electronic-signature/warnings-electronic-signature.md), 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](#firmatario). |
| `identity_used` | object | L'identità verificata su cui si basa la firma. Consulta [Firmatario](#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](#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](#il-pdf-probatorio) di questo firmatario, una volta firmato. |
| `warnings` | array | Elementi `{ "code", "node_id" }` per ciascun [avviso](https://docs.didit.me/it/core-technology/electronic-signature/warnings-electronic-signature.md) generato. |
| `validation` | object \| null | L'ultima verifica crittografica dei documenti firmati. Consulta [Rivalidare una firma](#convalida-nuovamente-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](#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](https://docs.didit.me/it/core-technology/electronic-signature/overview.md#campi-sul-documento) 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](https://docs.didit.me/it/sessions-api/electronic-signature/download-field-image.md). |
| `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.

```bash theme={null}
# 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](https://docs.didit.me/it/sessions-api/electronic-signature/download-signed-document.md) |
| `GET .../evidence/` | [Scarica il documento probatorio della firma](https://docs.didit.me/it/sessions-api/electronic-signature/download-evidence.md) |
| `GET .../fields/{field_id}/image/` | [Scarica un'immagine della firma](https://docs.didit.me/it/sessions-api/electronic-signature/download-field-image.md) |
| `POST .../validate/` | [Valida le firme](https://docs.didit.me/it/sessions-api/electronic-signature/validate-signatures.md) |

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:

1. Le pagine del documento mostrato al firmatario, con ciascun valore del campo impresso nel punto in cui hai posizionato il campo.
2. La pagina probatoria, a meno che tu non abbia disattivato `signature_evidence_page`.
3. 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](https://docs.didit.me/it/sessions-api/generate-pdf.md) 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.

## Correlati

* [Panoramica sulla firma elettronica](https://docs.didit.me/it/core-technology/electronic-signature/overview.md)
* [Avvisi sulla firma elettronica](https://docs.didit.me/it/core-technology/electronic-signature/warnings-electronic-signature.md)
* [Modelli di dati: firma elettronica](https://docs.didit.me/it/reference/data-models.md#firma-elettronica)
* [Webhook](https://docs.didit.me/it/integration/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.