API Probe

Un rând Evidence este un artefact capturat în timpul unei sesiuni — o captură, o tablă, un clip video, o înregistrare sau un document încărcat. Fiecare rând poartă un sha256 + byte_size + mime astfel încât lanțul de verificare a integrității poate dovedi că octeții nu au fost modificați între captură și audit.

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

Tipuri

Tip	Capturat de	Note
`snapshot`	Operator sau partea de teren	Un singur cadru fix (JPEG). Cel mai frecvent tip.
`whiteboard`	Operator	Export Excalidraw — PNG + JSON canonic. Vedeți Tablouri.
`clip`	Operator	Un MP4 scurt tăiat din sesiunea live — folosit pentru a capta mișcarea pe care o demonstrează utilizatorul de teren.
`recording`	Sistem	Înregistrarea completă a sesiunii. Postprocesată la libx264 medium / crf20 după încheierea sesiunii.
`document`	Operator	Fișier atașat din chatul din sesiune (PDF-uri, fotografii etc.). Baza pentru PDF-pentru-semnătură.

Stare

Stare	Semnificație
`pending`	Rând creat; octeții nu sunt încă în stocarea de obiecte.
`uploading`	Încărcare multipart în curs.
`ready`	Octeții sunt persistați; sha256 + byte_size sunt finalizate. Doar rândurile `ready` pot fi descărcate.
`failed`	Captura sau încărcarea a fost întreruptă. `completed_at` este null.

Listați probele sesiunii

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

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

Parametri de interogare

Parametru	Tip	Note
`kind`	string	Filtru — unul dintre `snapshot`, `whiteboard`, `clip`, `recording`, `document`.
`limit`	int	Maxim 100. Implicit 25.
`cursor`	opaque	Din răspunsul anterior, câmpul `next_cursor`.

Obțineți un URL de descărcare semnat

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

Returnează un URL presemnat de scurtă durată de la care clientul preia octeții bruți. URL-ul indică direct către backendul de stocare de obiecte, astfel încât descărcările ocolesc serverele noastre de aplicație — fără costuri de egress de lățime de bandă din partea dvs. a API-ului public.

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

Reapelați când URL-ul expiră — fără penalizare de rate-limit pentru generări repetate. După descărcare, calculați hash-ul octeților cu SHA-256 și comparați-l cu sha256 returnat pentru a verifica integritatea fișierului cap la cap.

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

Erori frecvente

Stare	Cod	Când
403	`permission_denied`	Credențialul nu are `evidence:read`.
404	`not_found`	Rândul Evidence nu există în organizația credențialului.
409	`evidence_not_ready`	Descărcare solicitată pe un rând al cărui `status` nu este `ready`.
410	`retention_expired`	Politica de retenție a organizației a depășit limita de vârstă a rândului; octeții au fost șterși din stocarea de obiecte.

Note

Fără POST/PATCH/DELETE. Probele sunt capturate pe partea clientului (operator + SPA de teren) în timpul sesiunii. API-ul public este doar-citire pe această resursă.
Retenție. Fiecare organizație configurează o fereastră de retenție (implicit 7 ani pentru implementările conforme eIDAS). După fereastră, regulile de ciclu de viață ale stocării de obiecte șterg octeții; rândul rămâne pentru ca lanțul de audit să nu se rupă, dar /download returnează 410.
Ancorat în lanțul de audit. Fiecare rând ready își contribuie sha256 la lanțul de hash per sesiune, care este ancorat la TSA la încheierea sesiunii. Capul lanțului + chitanța TSA sunt accesibile prin endpoint-ul de verificare a auditului din SPA.