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.

In tutti i casi le richieste devono includere l'autenticazione con API key.

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 per installazione e scelta del canale.

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:

{
  "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"
  }
}

Risposta (201 Created):

{
  "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).

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

Endpoint: POST /v1/data-certifications

Body:

{
  "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
}

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

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

Endpoint: POST /v1/file-certifications-attachments

Body:

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

Risposta (201 Created):

[
  {
    "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.

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

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.

Endpoint: POST /v1/file-certifications

Body:

{
  "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"
  }
}

Risposta (201 Created):

{
  "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).

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.

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

Endpoint: GET /v1/certifications/{reportId}

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

Risposta (certificazione in corso):

{
  "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):

{
  "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:

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/1.1 500 Internal Server Error
Content-Type: application/problem+json

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

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 per i dettagli sulla verifica.

Per il formato completo delle risposte di errore, vedi Errori API.