Concepts

Ce que sont réellement une Session, une ligne de preuve 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 org correspond à un compte client. Toutes les autres ressources (sessions, preuves, événements d'audit, utilisateurs) sont rattachées à une Org via la sécurité au niveau des lignes sur les tables Postgres sous-jacentes. Un bug dans le code applicatif ne peut pas franchir les tenants — la base de données refusera la requête.

Une Org possède : des membres (utilisateurs avec accès basé sur les rôles), une identité de marque (logo / couleurs / pied de page PDF), un abonnement de facturation, des données KYB d'entité juridique facultatives, une configuration SSO facultative et une politique de conservation.

Membre, Rôle, Permission

Un L'adhésion est le lien entre un Utilisateur et une Org. Un utilisateur peut détenir des adhésions dans plusieurs orgs et basculer entre elles (l'org active est portée par une revendication JWT).

Chaque Org amorce quatre rôles système à la création :

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

Les admins d'org 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 + contre-vérifiées par la RLS au niveau de la base de données.

Session

Une inspection. L'unité de facturation (vous payez par session close) et l'unité de preuve (une chaîne d'audit est par session, pas par org).

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 facultatifs), un état de consentement, une position GPS facultative, des notes facultatives, une chaîne d'audit et — une fois close — 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 facultatifs 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'Org.

Preuve

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

snapshot — photo fixe issue de la caméra de l'utilisateur terrain.
annotation — dessin superposé sur 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 de preuve possède un SHA-256 de son contenu binaire, stocké dans la chaîne d'audit. Toute altération du fichier après coup échoue à la vérification.

Chaîne d'audit

L'épine dorsale cryptographique. Chaque événement d'une session — création de session, octroi de consentement, enregistrement GPS, capture de preuve, annotation, enregistrement du tableau blanc, signature, fin de session — émet une ligne AuditEvent 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 déclencheur en ajout seul bloque UPDATE + DELETE sur la table.

TimestampToken (ancre TSA)

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

YodaLedger — Ancre sur la blockchain Tezos. Finalité en ~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é à l'article 42 eIDAS.
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 l'une des TSA disparaît, les deux autres ancrent toujours la chaîne. Un auditeur peut vérifier auprès de chacune 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. Convient aux archives internes.
AES (signature électronique avancée) — certificat de signature lié à l'identité, ancré PAdES B-T. Convient à la plupart des contrats B2B.
QES (signature électronique qualifiée) — niveau eIDAS le plus élevé, équivalent juridique d'une signature manuscrite dans toute l'UE. Conditionné à la vérification KYB de l'organisation émettrice.

Campagne (facultatif)

Un regroupement logique de sessions pour un reporting par lots — « Sinistres auto T2 2026 » ou « Réserves 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 la livraison.

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