API de pruebas

Una fila de prueba es un artefacto capturado durante una sesión: una instantánea, una pizarra, un clip de vídeo, una grabación o un documento cargado. Cada fila lleva un sha256 + byte_size + mime para que la cadena de verificación de integridad pueda probar que los bytes no fueron manipulados entre la captura y la auditoría.

El objeto de prueba

{
  "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 o lado de campo	Fotograma fijo único (JPEG). El tipo más común.
`whiteboard`	Operador	Exportación de Excalidraw: PNG + JSON canónico. Consulte Pizarras.
`clip`	Operador	Corte MP4 corto de la sesión en vivo: se usa para capturar el movimiento que el usuario de campo demuestra.
`recording`	Sistema	Grabación completa de la sesión. Postprocesada a libx264 medium / crf20 tras finalizar la sesión.
`document`	Operador	Adjunto de archivo del chat en sesión (PDFs, fotos, etc.). Base para el PDF-para-firma.

Estado

Estado	Significado
`pending`	Fila creada; los bytes aún no están en el almacenamiento de objetos.
`uploading`	Carga multiparte en curso.
`ready`	Los bytes están persistidos; sha256 + byte_size están finalizados. Solo las filas `ready` son descargables.
`failed`	Captura o carga abortada. `completed_at` es nulo.

Listar las pruebas de la sesión

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

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

Parámetros de consulta

Parámetro	Tipo	Notas
`kind`	string	Filtro: uno de `snapshot`, `whiteboard`, `clip`, `recording`, `document`.
`limit`	int	Máximo 100. Predeterminado 25.
`cursor`	opaque	De la respuesta anterior `next_cursor`.

Obtener una URL de descarga firmada

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

Devuelve una URL prefirmada de corta duración desde la que el cliente obtiene los bytes en bruto. La URL apunta directamente al backend de almacenamiento de objetos, de modo que las descargas evitan nuestros servidores de aplicación: sin cargos por egress de ancho de banda desde su extremo de la 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"
}

Vuelva a llamar cuando la URL caduque: sin penalización de límite de tasa por emisiones repetidas. Tras descargar, calcule el hash de los bytes con SHA-256 y compárelo con el sha256 devuelto para verificar que el archivo está intacto de extremo a extremo.

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

Errores comunes

Estado	Código	Cuándo
403	`permission_denied`	La credencial carece de `evidence:read`.
404	`not_found`	La fila de prueba no existe en la organización de la credencial.
409	`evidence_not_ready`	Descarga solicitada en una fila cuyo `status` no es `ready`.
410	`retention_expired`	La política de retención de la organización ha superado el corte de edad de la fila; los bytes se han purgado del almacenamiento de objetos.

Notas

Sin POST/PATCH/DELETE. Las pruebas se capturan del lado del cliente (SPA de operador + campo) durante la sesión. La API pública es de solo lectura en este recurso.
Retención. Cada organización configura una ventana de retención (predeterminada de 7 años para despliegues conformes con eIDAS). Tras la ventana, las reglas de ciclo de vida del almacenamiento de objetos purgan los bytes; la fila permanece para que la cadena de auditoría no se rompa, pero /download devuelve 410.
Anclado en la cadena de auditoría. Cada fila ready aporta su sha256 a la cadena de hash por sesión, que se ancla en el TSA al finalizar la sesión. La cabeza de la cadena + el recibo del TSA son accesibles a través del endpoint de verificación de auditoría del lado de la SPA.