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.

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

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

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.

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.

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 per scegliere il server corretto e installarlo.

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

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.

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:

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 — un oggetto JSON con tre campi top-level:

• 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.

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

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)

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.

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:

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

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

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:

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

• Flusso di chiamate Certificazione — Guida operativa con sequenze di chiamate API
• Errori API — Formato RFC 9457, elenco codici e pagine di dettaglio per ogni tipo di errore
• Specifica OpenAPI — Riferimento tecnico degli endpoint