# Certificazione — Panoramica

Una **certificazione** è il processo con cui uno o più file digitali vengono certificati crittograficamente per attestarne:

- l'**esistenza** a un determinato momento (timestamp),
- l'**integrità** (i file non sono stati alterati dopo la certificazione),
- la **provenienza** (l'utente che ha effettuato la certificazione).


Il risultato è un insieme di artefatti firmati digitalmente che costituiscono la prova della certificazione.

## Le tre modalità

La Public API offre **tre modalità** per creare una certificazione, a seconda di come viene fornito il contenuto:

### Certificazione dati

Il client invia **dati chiave-valore in formato stringa** nel campo obbligatorio `data`. TrueScreen certifica solo quelle coppie (nessun upload di file, nessun elenco di hash).

- **Endpoint:** `POST /v1/data-certifications`
- **Chiamate necessarie:** 1
- **Livello di sicurezza:** inferiore — i dati sono dichiarati dal chiamante (simile alla certificazione hash).
- **Costo:** **1 credito per certificazione** (indipendentemente da quante coppie chiave-valore sono in `data`).


Usa `data` per il contenuto certificato

### Certificazione hash

Il client invia un elenco di **nomi file e hash** (SHA-256) già calcolati. TrueScreen certifica gli hash senza ricevere i file originali.

- **Endpoint:** `POST /v1/hash-certifications`
- **Chiamate necessarie:** 1
- **Livello di sicurezza:** inferiore — il sistema non può verificare che gli hash corrispondano a file reali.
- **Costo:** **1 credito per ogni hash** inviato.


### Certificazione file

Il client **carica i file** tramite URL di upload temporanei. TrueScreen riceve i file originali, ne calcola gli hash e procede alla certificazione.

- **Endpoint:** `POST /v1/file-certifications-attachments` + upload + `POST /v1/file-certifications`
- **Chiamate necessarie:** 3 (registrazione file → upload → creazione certificazione)
- **Livello di sicurezza:** superiore — i file originali vengono processati dal sistema.
- **Costo:** **1 credito per ogni file** caricato.


Su ogni elemento di `files` in **`POST /v1/file-certifications-attachments`**, **`creation_datetime`** è opzionale (ISO 8601 `date-time`, stesso oggetto di `file_name`). Se presente e valido, viene utilizzata come data di creazione nel **jsonData** per quell’allegato. Vedi [Flusso di chiamate Certificazione](/it/certification-workflow#3-certificazione-file).

### Confronto rapido

| Aspetto | Certificazione hash | Certificazione dati | Certificazione file |
|  --- | --- | --- | --- |
| **Input** | Nomi file + hash (SHA-256) | Stringhe chiave-valore in `data` | File da caricare |
| **Upload file** | No | No | Sì (URL presigned) |
| **Chiamate API** | 1 | 1 | 3 |
| **Sicurezza** | Inferiore | Inferiore | Superiore |
| **Costo crediti** | 1 per hash | 1 per certificazione | 1 per file |


## Certificazione tramite MCP

TrueScreen espone i flussi di certificazione anche tramite MCP.

- `truescreen_create_hash_certification`, `truescreen_create_data_certification`, `truescreen_get_certification` e `truescreen_wait_for_certification` sono disponibili sia sul server MCP **remoto** sia su quello **locale**.
- La certificazione file è disponibile solo sul server MCP **locale** tramite `truescreen_create_file_certification_attachments`, `truescreen_upload_file` e `truescreen_create_file_certification`.


Vedi [Integrazione MCP](/it/mcp-integration) per scegliere il server corretto e installarlo.

## Artefatti prodotti

Al completamento della certificazione, il sistema produce tre tipologie di file:

| Artefatto | Formato | Leggibilità | Descrizione |
|  --- | --- | --- | --- |
| **jsonData** | JSON | Machine-readable | Hash dei file certificati, metadati dei file e metadati utente. Contiene tutte le informazioni per la verifica dell'integrità. |
| **Report PDF** (opzionale) | PDF | Human-readable | Report leggibile con i dati salienti dal jsonData. Utile per consultazione diretta (avvocati, auditor, ecc.). Generato solo se previsto dalla configurazione. |
| **XML firmato** | XML + XAdES | Entrambe | Contiene gli hash di jsonData e, quando presente, del report PDF. Firmato digitalmente e marcato temporalmente. È l'elemento che conferisce valore probatorio alla certificazione. |


L'**XML firmato** garantisce:

- **Integrità** — qualsiasi modifica a jsonData o al report PDF (quando presente) invalida la firma.
- **Autenticità** — la firma digitale attesta che la certificazione è stata emessa dal sistema TrueScreen.
- **Data certa** — la marca temporale prova che i dati esistevano al momento della certificazione.


## Processo asincrono

La generazione della certificazione è **asincrona**: la risposta alla richiesta di creazione restituisce `status: "processing"` e un `report_id`. Il completamento si verifica in un secondo momento.

Hai **due opzioni** per sapere quando la certificazione è pronta:

### Webhook

Passa un **`webhook_url`** nel body della richiesta di creazione. Quando l'elaborazione **termina** (successo o errore), TrueScreen effettua una callback **HTTP POST** verso quell'URL.

Il payload della callback segue il formato envelope **[Standard Webhooks](https://www.standardwebhooks.com)** — un oggetto JSON con tre campi top-level:

| Campo | Tipo | Descrizione |
|  --- | --- | --- |
| `type` | stringa | Tipo di evento: `certification.completed` o `certification.error` |
| `timestamp` | stringa | Timestamp ISO 8601 di quando l'evento si è verificato |
| `data` | oggetto | Payload dell'evento (vedi sotto) |


- **`certification.completed`** — `data` coincide con la risposta **200** di `GET /v1/certifications/{reportId}` (`status: "completed"`, array `files` con URL firmati).
- **`certification.error`** — `data` contiene un documento **`application/problem+json`** (RFC 9457) con la stessa forma della risposta di errore di quella `GET`.


Il `Content-Type` è sempre `application/json`; la distinzione successo/errore si fa tramite il campo `type`.

#### Verifica della firma

Ogni callback include tre header **Standard Webhooks** per la verifica della firma:

| Header | Descrizione |
|  --- | --- |
| `webhook-id` | Identificativo univoco dell'evento (chiave di idempotency) |
| `webhook-timestamp` | Timestamp Unix (secondi dall'epoch) del tentativo di invio |
| `webhook-signature` | Firma(e) HMAC-SHA256 nel formato `v1,<base64>` |


La firma è calcolata su `{webhook-id}.{webhook-timestamp}.{raw_body}` usando un **webhook signing secret** — una chiave dedicata (prefisso `whsec_`) separata dall'API key, ottenuta dal portale TrueScreen. Per verificare:

1. Ricostruire il contenuto firmato: `"{webhook-id}.{webhook-timestamp}.{body}"`
2. Calcolare `HMAC-SHA256` con il signing secret decodificato
3. Confrontare (tempo costante) con ogni firma `v1,...` nell'header
4. Rifiutare se `|now - webhook-timestamp| > 300s` (protezione anti-replay)


### Polling

Interroga periodicamente **`GET /v1/certifications/{reportId}`** usando il `report_id` ricevuto nella risposta di creazione. Quando la certificazione è completata, la risposta è **200** con `status: "completed"` e l'array `files` con gli URL firmati. Se l'elaborazione asincrona fallisce, l'API restituisce un **codice di errore HTTP** e **`application/problem+json`**—vedi OpenAPI e [Flusso chiamate certificazione](/it/certification-workflow).

## Metadati aggiuntivi

In entrambi gli endpoint di creazione puoi passare un campo opzionale **`metadata`**: un oggetto chiave-valore libero con dati personalizzati (es. numero pratica, nome cliente, riferimento contratto).

Le chiavi e i valori del metadata vengono inclusi nel **jsonData** e, quando generato, nel **report PDF**.

Esempio:

```json
{
  "metadata": {
    "case_number": "2024/001",
    "client_name": "Mario Rossi",
    "contract_ref": "CTR-20240315"
  }
}
```

## Crediti

Ogni certificazione ha un costo in **crediti** (unità di valuta acquistabile dal portale TrueScreen).

| Modalità | Costo |
|  --- | --- |
| **Certificazione hash** | 1 credito per ogni hash inviato |
| **Certificazione file** | 1 credito per ogni file caricato |


I crediti vengono **detratti al momento della creazione**, prima che la lavorazione asincrona abbia inizio. Se il saldo crediti è insufficiente, la richiesta viene rifiutata con un errore e nessun credito viene scalato.

Puoi verificare il saldo in qualsiasi momento con **`GET /v1/credits`**:

```json
{
  "purchased": 100,
  "used": 35,
  "available": 65,
  "expires_at": "2026-12-31"
}
```

## Riferimenti

- [Flusso di chiamate Certificazione](/it/certification-workflow) — Guida operativa con sequenze di chiamate API
- [Errori API](/it/errors) — Formato RFC 9457, elenco codici e pagine di dettaglio per ogni tipo di errore
- [Specifica OpenAPI](/it/openapi) — Riferimento tecnico degli endpoint