API Evidence

Une ligne Evidence correspond à un artefact capturé pendant une session — une capture, un tableau blanc, un clip vidéo, un enregistrement ou un document téléversé. Chaque ligne porte un sha256 + byte_size + mime afin que la chaîne de vérification d'intégrité puisse prouver que les octets n'ont pas été altérés entre la capture et l'audit.

L'objet 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"
}

Types

Type	Capturé par	Notes
`snapshot`	Opérateur ou côté terrain	Image fixe unique (JPEG). Le type le plus courant.
`whiteboard`	Opérateur	Export Excalidraw — PNG + JSON canonique. Voir Tableaux blancs.
`clip`	Opérateur	Court MP4 découpé dans la session en direct — sert à capturer un mouvement que l'utilisateur terrain démontre.
`recording`	Système	Enregistrement complet de la session. Post-traité en libx264 medium / crf20 après la fin de la session.
`document`	Opérateur	Pièce jointe issue du chat en session (PDF, photos, etc.). Fondation pour le PDF à signer.

Statut

Statut	Signification
`pending`	Ligne créée ; octets pas encore dans le stockage objet.
`uploading`	Téléversement multipart en cours.
`ready`	Les octets sont persistés ; sha256 + byte_size sont finalisés. Seules les lignes `ready` sont téléchargeables.
`failed`	Capture ou téléversement interrompu. `completed_at` est null.

Lister les preuves d'une session

GET /api/v1/public/sessions/{session_id}/evidence — Portée evidence:read

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

Paramètres de requête

Paramètre	Type	Notes
`kind`	string	Filtre — l'un de `snapshot`, `whiteboard`, `clip`, `recording`, `document`.
`limit`	int	Max 100. Par défaut 25.
`cursor`	opaque	Repris de la réponse précédente : `next_cursor`.

Obtenir une URL de téléchargement signée

GET /api/v1/public/evidence/{evidence_id}/download — Portée evidence:read

Renvoie une URL présignée à courte durée de vie depuis laquelle le client récupère les octets bruts. L'URL pointe directement vers le backend de stockage objet, de sorte que les téléchargements contournent nos serveurs applicatifs — aucun frais d'egress de bande passante de votre côté de l'API publique.

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

Rappelez lorsque l'URL expire — aucune pénalité de limite de débit pour des émissions répétées. Après téléchargement, hachez les octets avec SHA-256 et comparez au sha256 renvoyé pour vérifier que le fichier est intact de bout en bout.

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

Erreurs courantes

Statut	Code	Quand
403	`permission_denied`	L'identifiant ne dispose pas du scope `evidence:read`.
404	`not_found`	La ligne de preuve n'existe pas dans l'organisation de l'identifiant.
409	`evidence_not_ready`	Téléchargement demandé sur une ligne dont le `status` n'est pas `ready`.
410	`retention_expired`	La politique de rétention de l'organisation a dépassé le seuil d'âge de la ligne ; les octets ont été purgés du stockage objet.

Notes

Pas de POST/PATCH/DELETE. Les preuves sont capturées côté client (SPA opérateur + terrain) pendant la session. L'API publique est en lecture seule sur cette ressource.
Rétention. Chaque organisation configure une fenêtre de rétention (7 ans par défaut pour les déploiements conformes eIDAS). Passé la fenêtre, les règles de cycle de vie du stockage objet purgent les octets ; la ligne demeure pour ne pas casser la chaîne d'audit, mais /download renvoie 410.
Ancrée dans la chaîne d'audit. Chaque ligne ready contribue son sha256 à la chaîne de hachage par session, laquelle est ancrée à la TSA à la fin de la session. La tête de chaîne + le reçu TSA sont accessibles via l'endpoint de vérification d'audit côté SPA.