Concepts

Ce que sont réellement une Session, une ligne Evidence et une Chaîne d'audit, en aussi peu de mots que possible. Lisez ceci une fois et la référence API prendra tout son sens.

Organisation

Le tenant de plus haut niveau. Une organisation correspond à un compte client. Toute autre ressource (sessions, preuves, événements d'audit, utilisateurs) est rattachée à une organisation via la sécurité au niveau ligne sur les tables Postgres sous-jacentes. Un bug dans le code applicatif ne peut pas franchir la frontière entre tenants — la base de données refusera la requête.

Une organisation possède : des membres (utilisateurs avec accès basé sur les rôles), un branding (logo / couleurs / pied de page PDF), un abonnement de facturation, des données KYB d'entité juridique optionnelles, une configuration SSO optionnelle, et une politique de rétention.

Membre, Rôle, Permission

Un L'adhésion est la liaison entre un Utilisateur et une Organisation. Un utilisateur peut détenir des adhésions dans plusieurs organisations et basculer entre elles (l'organisation active est transportée comme un claim JWT).

Chaque organisation initialise quatre rôles système à sa création :

org_admin — contrôle total. Facturation, membres, branding, rétention.
inspector — peut mener des inspections, capturer des preuves, signer des rapports.
observer — accès en lecture seule aux sessions + aux données d'audit.
auditor — accès en lecture seule plus la permission de vérification de chaîne.

Les admins d'organisation peuvent créer des rôles personnalisés en composant le catalogue de permissions. Les permissions sont vérifiées par slug au niveau de la vue + recoupées par RLS au niveau de la base de données.

Session

Une inspection. L'unité de facturation (vous payez par session clôturée) et l'unité de preuve (une chaîne d'audit est par session, pas par organisation).

Une session possède : un opérateur (le membre de votre équipe qui l'a démarrée), un ou plusieurs participants (l'utilisateur terrain, plus des observateurs optionnels), l'état du consentement, une position GPS optionnelle, des notes optionnelles, une chaîne d'audit, et — une fois clôturée — des jetons d'horodatage ancrés par TSA.

Participant

Une personne dans une session. Il y a un opérateur par session et au moins un utilisateur terrain ; des observateurs supplémentaires optionnels sont pris en charge. Les utilisateurs terrain rejoignent via une URL signée à usage unique (aucun compte requis) ; les opérateurs + observateurs sont membres de l'organisation.

Preuve

Un élément de preuve capturé pendant une session. Types :

snapshot — photo fixe depuis la caméra de l'utilisateur terrain.
annotation — dessin superposé à une capture ou à un tableau blanc.
whiteboard — canevas Excalidraw en session exporté en PNG + état.
clip — court segment vidéo.
document — fichier téléversé (utilisé par la couche de chat pour le PDF à signer).

Chaque ligne Evidence porte un SHA-256 de son contenu binaire, stocké dans la chaîne d'audit. Altérer le fichier après coup fait échouer la vérification.

Chaîne d'audit

L'épine dorsale cryptographique. Chaque événement d'une session — création de session, octroi du consentement, enregistrement GPS, capture de preuve, annotation, sauvegarde de tableau blanc, signature, fin de session — émet une AuditEvent ligne avec :

{
  "session": "<uuid>",
  "sequence": N,
  "occurred_at": "<iso8601>",
  "kind": "evidence.snapshot_added",
  "actor": { "user": <id|null>, "participant": <id|null> },
  "payload": { /* event-specific */ },
  "prev_hash": "<sha256 of previous event>",
  "hash": "<sha256 of canonical_json of this event>"
}

Le premier événement utilise prev_hash = "0" * 64 (genèse). Chaque événement suivant utilise le hachage de l'événement précédent comme prev_hash et incrémente sequence de 1. Un verrou consultatif Postgres sérialise les écritures par session ; un trigger append-only bloque UPDATE + DELETE sur la table.

TimestampToken (ancre TSA)

En fin de session (et lors d'un « stamp now » déclenché par l'opérateur), la tête de chaîne actuelle est soumise à trois autorités d'horodatage indépendantes :

YodaLedger — Ancre sur la blockchain Tezos. Finalité de ~15-20 minutes. Asynchrone ; nous recevons un callback lorsque le bloc est confirmé.
FreeTSA — Horodatage RFC 3161. Synchrone ; jeton renvoyé immédiatement. Interchangeable avec un QTSP payant (DataSure) pour la conformité eIDAS Art. 42.
OpenTimestamps — Ancre Bitcoin via le protocole de calendrier OpenTimestamps. Asynchrone ; le chemin de mise à niveau s'exécute sur un balayage Celery.

Trois par conception — si une TSA disparaît, les deux autres ancrent toujours la chaîne. Un auditeur peut vérifier contre l'une d'elles indépendamment à l'aide d'explorateurs de blocs publics / d'endpoints de vérification.

Signature (SES / AES / QES)

Trois niveaux eIDAS, tous sur le même PDF de rapport d'audit :

SES (Signature Électronique Simple) — adossée à la chaîne d'audit, sans certificat de signature. Adaptée aux dossiers internes.
AES (Signature Électronique Avancée) — certificat de signature lié à l'identité, ancrage PAdES B-T. Adaptée à la plupart des contrats B2B.
QES (Signature Électronique Qualifiée) — le plus haut niveau eIDAS, équivalent légal d'une signature manuscrite dans toute l'UE. Conditionné à la vérification KYB de l'organisation émettrice.

Campagne (optionnel)

Un regroupement logique de sessions pour un reporting groupé — « Sinistres auto T2 2026 » ou « Défauts de réception du site A ». Les sessions ne nécessitent pas de campagne ; c'est une commodité de reporting.

Webhook

Une URL enregistrée par le client qui reçoit des POST d'événements signés HMAC. Types d'événements : session.created, session.completed, participant.joined, participant.left, evidence.added, recording.ready, audit.anchored, signature.completed, plus un webhook.test pour la vérification de livraison.

Signature : en-tête de style Stripe t=...,v1=... avec HMAC-SHA256 sur <timestamp>.<body>. Le helper constructEvent() du SDK vérifie en temps constant avec une tolérance de dérive d'horloge de 5 minutes.