API Evidence

Una riga Evidence è un artefatto catturato durante una sessione — uno snapshot, una lavagna, un clip video, una registrazione o un documento caricato. Ogni riga porta uno sha256 + byte_size + mime così la catena di verifica dell'integrità può dimostrare che i byte non sono stati manomessi tra la cattura e l'audit.

L'oggetto Evidence

{
  "id": "ev-7f3a...",
  "session": "0c8f4d2e-1a3b-4c5d-9e7f-1234567890ab",
  "kind": "snapshot",
  "status": "ready",
  "mime": "image/jpeg",
  "byte_size": 184523,
  "sha256": "f9cc12fda76c30dcc9bee627baed6c9e8fe11b813313de70b1463f9f73e5e418",
  "captured_at": "2026-05-23T10:14:02.481Z",
  "created_at": "2026-05-23T10:14:02.917Z",
  "completed_at": "2026-05-23T10:14:03.211Z"
}

Tipi

Tipo	Catturato da	Note
`snapshot`	Operatore o lato campo	Singolo fotogramma (JPEG). Il tipo più comune.
`whiteboard`	Operatore	Export Excalidraw — PNG + JSON canonico. Vedi Lavagne.
`clip`	Operatore	Breve MP4 tagliato dalla sessione live — usato per catturare il movimento che l'utente sul campo dimostra.
`recording`	Sistema	Registrazione completa della sessione. Post-processata a libx264 medium / crf20 al termine della sessione.
`document`	Operatore	Allegato dalla chat in-sessione (PDF, foto, ecc.). Fondamento per il PDF-per-firma.

Stato

Stato	Significato
`pending`	Riga creata; i byte non sono ancora nell'object storage.
`uploading`	Upload multipart in corso.
`ready`	I byte sono persistiti; sha256 + byte_size sono finalizzati. Solo le righe `ready` sono scaricabili.
`failed`	Cattura o upload interrotti. `completed_at` è null.

Elenca le prove di una sessione

GET /api/v1/public/sessions/{session_id}/evidence — scope evidence:read

curl "https://app.nexbasira.com/api/v1/public/sessions/0c8f.../evidence?kind=snapshot&limit=50" \
  -H "Authorization: Bearer nb_sec_..."

Query param

Param	Tipo	Note
`kind`	string	Filtro — uno tra `snapshot`, `whiteboard`, `clip`, `recording`, `document`.
`limit`	int	Max 100. Default 25.
`cursor`	opaque	Dalla risposta precedente `next_cursor`.

Ottieni un URL di download firmato

GET /api/v1/public/evidence/{evidence_id}/download — scope evidence:read

Restituisce un URL presigned a breve durata da cui il cliente recupera i byte grezzi. L'URL punta direttamente al backend di object storage così i download bypassano i nostri app server — nessun addebito di bandwidth-egress dal tuo lato dell'API pubblica.

curl "https://app.nexbasira.com/api/v1/public/evidence/ev-7f3a.../download" \
  -H "Authorization: Bearer nb_sec_..."

{
  "url": "https://s3.eu-central-1.amazonaws.com/nb-prod-evidence/orgs/.../snapshot.jpg?X-Amz-Algorithm=...",
  "expires_in_seconds": 900,
  "sha256": "f9cc12fda76c30dcc9bee627baed6c9e8fe11b813313de70b1463f9f73e5e418",
  "byte_size": 184523,
  "mime": "image/jpeg",
  "kind": "snapshot"
}

Richiama quando l'URL scade — nessuna penale di rate-limit per generazioni ripetute. Dopo il download, calcola l'hash dei byte con SHA-256 e confrontalo con lo sha256 restituito per verificare che il file sia intatto end-to-end.

# integrity check — Python
import hashlib, requests
r = requests.get(presigned["url"]); r.raise_for_status()
assert hashlib.sha256(r.content).hexdigest() == presigned["sha256"]

Errori comuni

Stato	Codice	Quando
403	`permission_denied`	La credenziale non ha `evidence:read`.
404	`not_found`	La riga Evidence non esiste nell'org della credenziale.
409	`evidence_not_ready`	Download richiesto su una riga il cui `status` non è `ready`.
410	`retention_expired`	La policy di retention dell'org ha superato il limite di età della riga; i byte sono stati eliminati dall'object storage.

Note

Nessun POST/PATCH/DELETE. Le prove sono catturate lato client (operatore + SPA sul campo) durante la sessione. L'API pubblica è in sola lettura su questa risorsa.
Retention. Ogni org configura una finestra di retention (default 7 anni per i deployment conformi a eIDAS). Dopo la finestra, le regole di lifecycle dell'object storage eliminano i byte; la riga resta così la catena di audit non si spezza, ma /download restituisce 410.
Ancorata nella catena di audit. Ogni riga ready contribuisce con il suo sha256 alla hash chain per sessione, che viene ancorata alla TSA al termine della sessione. La testa della catena + la ricevuta TSA sono raggiungibili tramite l'endpoint di audit-verify lato SPA.