API de Provas

Uma linha de Prova é um artefacto capturado durante uma sessão — uma captura, um quadro branco, um clip de vídeo, uma gravação ou um documento carregado. Cada linha transporta um sha256 + byte_size + mime para que a cadeia de verificação de integridade possa provar que os bytes não foram adulterados entre a captura e a auditoria.

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

Tipos

Tipo	Capturado por	Notas
`snapshot`	Operador ou lado do terreno	Fotograma único (JPEG). O tipo mais comum.
`whiteboard`	Operador	Exportação Excalidraw — PNG + JSON canónico. Ver Quadros brancos.
`clip`	Operador	MP4 curto cortado da sessão em direto — usado para capturar movimento que o utilizador de terreno demonstra.
`recording`	Sistema	Gravação completa da sessão. Pós-processada para libx264 medium / crf20 após o fim da sessão.
`document`	Operador	Anexo de ficheiro do chat em sessão (PDFs, fotografias, etc.). Base para o PDF-para-assinatura.

Estado

Estado	Significado
`pending`	Linha criada; bytes ainda não no armazenamento de objetos.
`uploading`	Upload multipart em curso.
`ready`	Os bytes estão persistidos; sha256 + byte_size estão finalizados. Apenas as linhas `ready` são transferíveis.
`failed`	A captura ou o upload foram abortados. `completed_at` é null.

Listar provas de uma sessão

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 params

Param	Tipo	Notas
`kind`	string	Filtro — um de `snapshot`, `whiteboard`, `clip`, `recording`, `document`.
`limit`	int	Máx. 100. Por defeito 25.
`cursor`	opaque	Da resposta anterior `next_cursor`.

Obter um URL de transferência assinado

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

Devolve um URL pré-assinado de curta duração de onde o cliente obtém os bytes em bruto. O URL aponta diretamente para o backend de armazenamento de objetos, pelo que as transferências contornam os nossos servidores de aplicação — sem cobranças de egress de largura de banda do seu lado da API pública.

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

Volte a chamar quando o URL expirar — sem penalização de limite de taxa por emissões repetidas. Após a transferência, faça o hash dos bytes com SHA-256 e compare com o sha256 devolvido para verificar que o ficheiro está intacto de ponta a ponta.

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

Erros comuns

Estado	Código	Quando
403	`permission_denied`	A credencial não tem `evidence:read`.
404	`not_found`	A linha de prova não existe na organização da credencial.
409	`evidence_not_ready`	Transferência pedida numa linha cujo `status` não é `ready`.
410	`retention_expired`	A política de retenção da organização ultrapassou o corte de idade da linha; os bytes foram purgados do armazenamento de objetos.

Notas

Sem POST/PATCH/DELETE. As provas são capturadas do lado do cliente (SPA do operador + do terreno) durante a sessão. A API pública é apenas de leitura neste recurso.
Retenção. Cada organização configura uma janela de retenção (por defeito 7 anos para deployments conformes ao eIDAS). Após a janela, as regras de ciclo de vida do armazenamento de objetos purgam os bytes; a linha permanece para que a cadeia de auditoria não quebre, mas /download devolve 410.
Ancorado na cadeia de auditoria. Cada linha ready contribui com o seu sha256 para a cadeia de hash por sessão, que é ancorada na TSA no fim da sessão. O topo da cadeia + o recibo da TSA são alcançáveis via o endpoint de verificação de auditoria do lado da SPA.