API důkazů

Řádek důkazu je jeden artefakt zachycený během relace — snímek, tabule, videoklip, nahrávka nebo nahraný dokument. Každý řádek nese sha256 + byte_size + mime aby řetězec ověření integrity mohl prokázat, že s bajty nebylo mezi zachycením a auditem manipulováno.

Objekt důkazu

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

Druhy

Druh	Zachyceno kým	Poznámky
`snapshot`	Operátor nebo strana terénu	Jeden statický snímek (JPEG). Nejčastější druh.
`whiteboard`	Operátor	Export z Excalidraw — PNG + kanonický JSON. Viz Tabule.
`clip`	Operátor	Krátký sestřih MP4 z živé relace — používá se k zachycení pohybu, který uživatel v terénu předvádí.
`recording`	Systém	Nahrávka celé relace. Po skončení relace se následně zpracuje do libx264 medium / crf20.
`document`	Operátor	Příloha souboru z chatu během relace (PDF, fotografie atd.). Základ pro PDF k podpisu.

Stav

Stav	Význam
`pending`	Řádek vytvořen; bajty ještě nejsou v objektovém úložišti.
`uploading`	Probíhá vícedílné nahrávání.
`ready`	Bajty jsou uloženy; sha256 + byte_size jsou finalizovány. Stažitelné jsou pouze `ready` řádky.
`failed`	Zachycení nebo nahrávání přerušeno. `completed_at` je null.

Výpis důkazů relace

GET /api/v1/public/sessions/{session_id}/evidence — Oprávnění evidence:read

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

Parametry dotazu

Parametr	Typ	Poznámky
`kind`	string	Filtr — jeden z `snapshot`, `whiteboard`, `clip`, `recording`, `document`.
`limit`	int	Max 100. Výchozí 25.
`cursor`	opaque	Z předchozí odpovědi `next_cursor`.

Získání podepsané URL ke stažení

GET /api/v1/public/evidence/{evidence_id}/download — Oprávnění evidence:read

Vrací krátkodobou předpodepsanou URL, ze které zákazník načte surové bajty. URL míří přímo na backend objektového úložiště, takže stahování obchází naše aplikační servery — z vaší strany veřejného API žádné poplatky za odchozí přenos.

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

Zavolejte znovu, když URL vyprší — za opakované generování není žádný postih omezením počtu požadavků. Po stažení zahashujte bajty pomocí SHA-256 a porovnejte s vráceným sha256 pro ověření, že soubor je od začátku do konce neporušený.

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

Časté chyby

Stav	Kód	Kdy
403	`permission_denied`	Přihlašovacím údajům chybí `evidence:read`.
404	`not_found`	Řádek důkazu v organizaci přihlašovacích údajů neexistuje.
409	`evidence_not_ready`	Stažení požadováno u řádku, jehož `status` není `ready`.
410	`retention_expired`	Retenční politika organizace překročila věkový limit řádku; bajty byly z objektového úložiště vymazány.

Poznámky

Žádné POST/PATCH/DELETE. Důkazy se zachycují na straně klienta (operátor + terénní SPA) během relace. Veřejné API je pro tento zdroj pouze pro čtení.
Retence. Každá organizace konfiguruje retenční okno (výchozích 7 let pro nasazení splňující eIDAS). Po uplynutí okna pravidla životního cyklu objektového úložiště vymažou bajty; řádek zůstává, aby se auditní řetězec nepřerušil, ale /download vrací 410.
Ukotveno v auditním řetězci. Každý ready řádek přispívá svým sha256 do hashovacího řetězce relace, který se při ukončení relace ukotví u TSA. Hlava řetězce + potvrzení TSA jsou dostupné přes endpoint ověření auditu na straně SPA.