# Flusso di chiamate Certificazione

Questa guida descrive come creare una certificazione tramite la Public API. Hai **tre modalità** a disposizione:

1. **Certificazione hash** — Una sola chiamata: invii nomi file e hash SHA-256 pre-calcolati. TrueScreen certifica gli hash senza ricevere i file originali.
2. **Certificazione dati** — Una sola chiamata: invii `title` e il campo obbligatorio `data` (stringhe chiave-valore). Nessun upload di file né elenco di hash.
3. **Certificazione file** — Tre chiamate in sequenza: registri i file, li carichi su URL temporanei, poi avvii la certificazione. TrueScreen riceve i file originali e ne calcola gli hash.


Per i concetti di base (artefatti prodotti, processo asincrono, crediti, metadati), vedi la [panoramica sulla certificazione](/it/certification-overview).

## Riferimento rapido

| Scenario | Chiamate |
|  --- | --- |
| [Certificazione hash](#1-certificazione-hash) | `POST /v1/hash-certifications` |
| [Certificazione dati](#2-certificazione-dati) | `POST /v1/data-certifications` |
| [Certificazione file](#3-certificazione-file) | `POST /v1/file-certifications-attachments` → `PUT upload_url` → `POST /v1/file-certifications` |
| [Consultare lo stato](#4-consultare-lo-stato-della-certificazione) | `GET /v1/certifications/{reportId}` |


In tutti i casi le richieste devono includere l'[autenticazione](/it#autenticazione) con API key.

## Certificazione tramite MCP

Gli stessi flussi di certificazione sono disponibili tramite MCP con tool curati invece di chiamate HTTP dirette.

- Su entrambi i server MCP puoi usare `truescreen_create_hash_certification`, `truescreen_create_data_certification`, `truescreen_get_certification` e `truescreen_wait_for_certification`.
- La certificazione file è disponibile solo sul server MCP locale, che espone anche `truescreen_create_file_certification_attachments`, `truescreen_upload_file` e `truescreen_create_file_certification`.


Vedi [Integrazione MCP](/it/mcp-integration) per installazione e scelta del canale.

## Casi d'uso

### 1. Certificazione hash

Hai già i file e i relativi hash SHA-256. Vuoi certificare che quegli hash esistevano a un determinato momento, senza caricare i file originali.

**Endpoint:** `POST /v1/hash-certifications`

**Body:**

```json
{
  "title": "Certificazione documenti progetto Alpha",
  "files": [
    {
      "file_name": "contratto.pdf",
      "hash": "2661f88efc456652aa9f65f6340fe0213e5bde437e3c613b2a235de81581161e"
    },
    {
      "file_name": "allegato-tecnico.pdf",
      "hash": "5c5ec4792053e87788d0be3f6c31c77f7e48e02466407da5c16ac1962a00e368"
    }
  ],
  "webhook_url": "https://example.com/webhook/certification",
  "generate_pdf_report": true,
  "metadata": {
    "case_number": "2024/001",
    "client_name": "Mario Rossi"
  }
}
```

| Campo | Obbligatorio | Descrizione |
|  --- | --- | --- |
| `title` | sì | Titolo della certificazione |
| `files` | sì | Array di oggetti con `file_name` e `hash` (SHA-256, 64 caratteri esadecimali) |
| `webhook_url` | no | URL per la callback al completamento |
| `generate_pdf_report` | no | Se generare il report PDF (default `true`) |
| `metadata` | no | Oggetto chiave-valore con dati personalizzati da includere nel jsonData e, quando generato, nel report PDF |


**Risposta (201 Created):**

```json
{
  "report_id": "d8c2aef3-72a7-4a5f-b0e7-4308a88c6cff",
  "status": "pending",
  "credits_amount": 2,
  "title": "Certificazione documenti progetto Alpha",
  "created_at": "2026-03-06T14:30:00Z"
}
```

- **`report_id`** — Identificativo univoco della certificazione. Usalo per consultare lo stato con `GET /v1/certifications/{reportId}`.
- **`status`** — Stato iniziale `"pending"`: la certificazione è in lavorazione asincrona.
- **`credits_amount`** — Crediti consumati: 1 per ogni hash inviato (in questo esempio, 2 hash = 2 crediti).


### 2. Certificazione dati

Vuoi certificare dati strutturati in formato stringa (riferimenti, campi contrattuali, identificativi CRM) senza caricare file né dichiarare hash.

**Endpoint:** `POST /v1/data-certifications`

**Body:**

```json
{
  "title": "Attestazione dati contratto",
  "data": {
    "case_number": "2024/001",
    "client_name": "Mario Rossi",
    "contract_ref": "CTR-20240315"
  },
  "webhook_url": "https://example.com/webhook/certification",
  "generate_pdf_report": true
}
```

| Campo | Obbligatorio | Descrizione |
|  --- | --- | --- |
| `title` | sì | Titolo della certificazione |
| `data` | sì | Oggetto con almeno una coppia chiave-valore; chiavi e valori devono essere stringhe |
| `webhook_url` | no | URL per la callback al completamento |
| `generate_pdf_report` | no | Se generare il report PDF (default `true`) |


**Risposta (201 Created):** stessa forma della certificazione hash (`report_id`, `status`, `credits_amount`, `title`, `created_at`). **`credits_amount`** è **1** per certificazione.

### 3. Certificazione file

Vuoi caricare i file originali affinché TrueScreen ne calcoli gli hash e li certifichi. Il processo richiede **tre passaggi** in sequenza.

#### Passo 1 — Registrare i file e ottenere gli URL di upload

**Endpoint:** `POST /v1/file-certifications-attachments`

**Body:**

```json
{
  "files": [
    { "file_name": "contratto.pdf" },
    {
      "file_name": "foto-sopralluogo.jpg",
      "creation_datetime": "2026-04-08T14:30:00.000Z"
    }
  ]
}
```

| Campo | Obbligatorio | Descrizione |
|  --- | --- | --- |
| `files` | sì | Array non vuoto. |
| `files[].file_name` | sì | Nome del file. |
| `files[].creation_datetime` | no | ISO 8601 `date-time` (non futuro). Opzionale: se presente e valido, usato in jsonData per quell’allegato come data di acquisizione. |


**Risposta (201 Created):**

```json
[
  {
    "file_name": "contratto.pdf",
    "upload_session_token": "sess_abc123def456",
    "upload_url": "https://s3.amazonaws.com/bucket/contratto.pdf?X-Amz-Signature=..."
  },
  {
    "file_name": "foto-sopralluogo.jpg",
    "upload_session_token": "sess_abc123def456",
    "upload_url": "https://s3.amazonaws.com/bucket/foto-sopralluogo.jpg?X-Amz-Signature=..."
  }
]
```

- **`upload_session_token`** — Token unico per la sessione di upload. È lo stesso per tutti i file della stessa richiesta. Lo userai nel passo 3.
- **`upload_url`** — URL firmato temporaneo (presigned URL) per caricare il file. Ha una scadenza di 120 secondi.


#### Passo 2 — Caricare i file

Per ogni file, esegui una richiesta **HTTP PUT** verso l'`upload_url` ricevuto, con il corpo della richiesta uguale al contenuto binario del file.

```http
PUT https://s3.amazonaws.com/bucket/contratto.pdf?X-Amz-Signature=... HTTP/1.1
Content-Type: application/pdf

<contenuto binario del file>
```

Il client deve usare esattamente l'URL ricevuto senza aggiungere header di autenticazione TrueScreen (la firma è nell'URL). L'unico header necessario è `Content-Type` con il MIME type del file.

Ripeti l'operazione per ogni file. **Tutti i file devono essere caricati** prima di procedere al passo 3; in caso contrario la creazione della certificazione fallirà con errore `TS-013`.

#### Passo 3 — Creare la certificazione

**Endpoint:** `POST /v1/file-certifications`

**Body:**

```json
{
  "title": "Certificazione sopralluogo cantiere",
  "upload_session_token": "sess_abc123def456",
  "webhook_url": "https://example.com/webhook/certification",
  "generate_pdf_report": true,
  "metadata": {
    "site_id": "CANT-042",
    "inspector": "Luigi Verdi"
  }
}
```

| Campo | Obbligatorio | Descrizione |
|  --- | --- | --- |
| `title` | sì | Titolo della certificazione |
| `upload_session_token` | sì | Token ricevuto nel passo 1 |
| `webhook_url` | no | URL per la callback al completamento |
| `generate_pdf_report` | no | Se generare il report PDF (default `true`) |
| `metadata` | no | Oggetto chiave-valore con dati personalizzati |


**Risposta (201 Created):**

```json
{
  "report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "credits_amount": 2,
  "title": "Certificazione sopralluogo cantiere",
  "created_at": "2026-03-06T15:00:00Z"
}
```

- **`credits_amount`** — Crediti consumati: 1 per ogni file caricato (in questo esempio, 2 file = 2 crediti).


#### Riassunto sequenza certificazione file

1. `POST /v1/file-certifications-attachments` con i nomi dei file (e opzionale `creation_datetime` per file) → ottieni `upload_session_token` e `upload_url` per ogni file.
2. `PUT upload_url` per ogni file → carica il contenuto binario.
3. `POST /v1/file-certifications` con `upload_session_token` → avvia la certificazione.


### 4. Consultare lo stato della certificazione

Il processo è **asincrono**: dopo la creazione, la certificazione è in stato `"pending"`. Puoi sapere quando è completata in due modi.

#### Polling

**Endpoint:** `GET /v1/certifications/{reportId}`

Interroga periodicamente l'endpoint passando il `report_id` ricevuto nella risposta di creazione.

**Risposta (certificazione in corso):**

```json
{
  "report_id": "d8c2aef3-72a7-4a5f-b0e7-4308a88c6cff",
  "status": "pending",
  "created_at": "2026-03-06T14:30:00Z",
  "title": "Certificazione documenti progetto Alpha",
  "files": []
}
```

**Risposta (certificazione completata):**

```json
{
  "report_id": "d8c2aef3-72a7-4a5f-b0e7-4308a88c6cff",
  "status": "completed",
  "created_at": "2026-03-06T14:30:00Z",
  "title": "Certificazione documenti progetto Alpha",
  "files": [
    {
      "type": "data",
      "url": "https://s3.example.com/d8c2aef3.json?X-Amz-Signature=..."
    },
    {
      "type": "report",
      "url": "https://s3.example.com/d8c2aef3.pdf?X-Amz-Signature=..."
    },
    {
      "type": "xml",
      "url": "https://s3.example.com/d8c2aef3.xml?X-Amz-Signature=..."
    }
  ]
}
```

I file restituiti nell'array `files` hanno un campo `type` che identifica il tipo di artefatto:

| `type` | Artefatto | Descrizione |
|  --- | --- | --- |
| `data` | jsonData | Documento JSON machine-readable con hash e metadati |
| `report` | Report PDF | Documento PDF human-readable con i dati salienti (presente solo se la generazione del report è prevista dalla configurazione) |
| `xml` | XML firmato | Envelope XML firmato digitalmente e marcato temporalmente |
| `media` | File originali | I file caricati (solo per certificazione file) |


Gli URL sono **firmati** (presigned) e hanno una scadenza temporale di 60 secondi: scarica i file entro il periodo di validità.

**Risposta (certificazione fallita dopo l'elaborazione asincrona):**

Se il `POST` di creazione è riuscito ma l'elaborazione successiva fallisce, **`GET /v1/certifications/{reportId}`** risponde con **`500`**, **`Content-Type: application/problem+json`**, e il seguente corpo problema RFC 9457:

```http
HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json
```

```json
{
  "type": "https://truescreen.redocly.app/errors/server-error",
  "title": "Certification processing error",
  "status": 500,
  "detail": "Digital signature error.",
  "code": "TS-014"
}
```

#### Webhook

Se hai passato un `webhook_url` nella richiesta di creazione, TrueScreen invia una **callback HTTP POST** quando l'elaborazione **termina — con successo o con errore**.

Il payload della callback usa il formato envelope **Standard Webhooks**:

- **`certification.completed`** — `data` coincide con la risposta **200** della `GET` (oggetto certificazione con `files`).
- **`certification.error`** — `data` contiene il documento **`application/problem+json`** che la `GET` restituirebbe per quell'esito.


Ogni callback è firmata con header Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`). Vedi [Certificazione — Panoramica](/it/certification-overview#verifica-della-firma) per i dettagli sulla verifica.

## Errori comuni

| Codice | Situazione | Cosa fare |
|  --- | --- | --- |
| `TS-001` | Payload malformato | Verifica la struttura JSON della richiesta |
| `TS-002` | Campo obbligatorio mancante | Controlla che `title`, `files` o `upload_session_token` siano presenti |
| `TS-008` | Crediti insufficienti | Verifica il saldo con `GET /v1/credits` e acquista crediti dal portale TrueScreen |
| `TS-010` | Certificazione non trovata | Verifica il `reportId` passato a `GET /v1/certifications/{reportId}` |
| `TS-012` | Upload session token già usato | Ogni `upload_session_token` può creare una sola certificazione |
| `TS-013` | Non tutti i file sono stati caricati | Completa l'upload di tutti i file prima di chiamare `POST /v1/file-certifications` |
| `TS-014` | Elaborazione certificazione non completata dopo la creazione | Vedi [Errori server](/it/errors/server-error#fallimento-elaborazione-certificazione); il webhook invia un evento `certification.error` |


Per il formato completo delle risposte di errore, vedi [Errori API](/it/errors).