API Materiału dowodowego

Wiersz Evidence to jeden artefakt zebrany podczas sesji — zrzut, tablica, klip wideo, nagranie lub przesłany dokument. Każdy wiersz zawiera sha256 + byte_size + mime aby łańcuch weryfikacji integralności mógł udowodnić, że bajty nie zostały zmanipulowane między zebraniem a audytem.

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

Rodzaje

Rodzaj	Zebrane przez	Uwagi
`snapshot`	Operator lub strona terenowa	Pojedyncza klatka (JPEG). Najczęstszy rodzaj.
`whiteboard`	Operator	Eksport Excalidraw — PNG + kanoniczny JSON. Zobacz Tablice.
`clip`	Operator	Krótki wycinek MP4 z sesji na żywo — używany do uchwycenia ruchu demonstrowanego przez użytkownika terenowego.
`recording`	System	Pełne nagranie sesji. Poddawane post-processingowi do libx264 medium / crf20 po zakończeniu sesji.
`document`	Operator	Załącznik pliku z czatu w sesji (PDF-y, zdjęcia itd.). Podstawa podpisu PDF.

Status

Status	Znaczenie
`pending`	Wiersz utworzony; bajty jeszcze nie w object storage.
`uploading`	Przesyłanie wieloczęściowe w toku.
`ready`	Bajty są utrwalone; sha256 + byte_size sfinalizowane. Do pobrania są wyłącznie wiersze `ready` .
`failed`	Zbieranie lub przesyłanie przerwane. `completed_at` jest null.

Listuj materiał dowodowy sesji

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

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

Parametry zapytania

Parametr	Typ	Uwagi
`kind`	string	Filtr — jeden z `snapshot`, `whiteboard`, `clip`, `recording`, `document`.
`limit`	int	Maks. 100. Domyślnie 25.
`cursor`	opaque	Z pola poprzedniej odpowiedzi `next_cursor`.

Uzyskaj podpisany URL do pobrania

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

Zwraca krótkotrwały wstępnie podpisany URL, z którego klient pobiera surowe bajty. URL wskazuje bezpośrednio na backend object storage, więc pobrania omijają nasze serwery aplikacji — bez opłat za wychodzący transfer po Państwa stronie publicznego API.

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

Wywołaj ponownie, gdy URL wygaśnie — brak kary limitu zapytań za powtarzane generowanie. Po pobraniu zhashuj bajty za pomocą SHA-256 i porównaj ze zwróconym sha256 aby zweryfikować, że plik jest nienaruszony od początku do końca.

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

Częste błędy

Status	Kod	Kiedy
403	`permission_denied`	Poświadczenie nie posiada `evidence:read`.
404	`not_found`	Wiersz materiału dowodowego nie istnieje w organizacji poświadczenia.
409	`evidence_not_ready`	Pobranie żądane dla wiersza, którego `status` nie jest `ready`.
410	`retention_expired`	Polityka retencji organizacji przekroczyła próg wieku wiersza; bajty zostały usunięte z object storage.

Uwagi

Brak POST/PATCH/DELETE. Materiał dowodowy jest zbierany po stronie klienta (operator + terenowe SPA) podczas sesji. Publiczne API jest na tym zasobie tylko do odczytu.
Retencja. Każda organizacja konfiguruje okno retencji (domyślnie 7 lat dla wdrożeń zgodnych z eIDAS). Po upływie okna reguły cyklu życia object storage usuwają bajty; wiersz pozostaje, aby łańcuch audytu się nie zerwał, ale /download zwraca 410.
Zakotwiczone w łańcuchu audytu. Każdy wiersz ready wnosi swój sha256 do łańcucha hashy per sesja, który jest zakotwiczany w TSA na koniec sesji. Głowica łańcucha + potwierdzenie TSA są osiągalne za pośrednictwem endpointu weryfikacji audytu po stronie SPA.