Contrat candidatREST JSONVersion 0.3

Guide de l’API

Une vue publique du cycle de vie et des ressources envisagées. Cette page prépare les intégrations ; elle ne constitue pas encore un contrat d’API stable.

Conventions Événements Rapports

Socle HTTP

Conventions candidates

Échanges HTTPS et corps JSON en UTF-8.
Jeton d’accès limité à une organisation, des rôles et des scopes.
Identifiants opaques ; le tenant_id est dérivé de l’autorisation et non accepté comme preuve d’accès.
En-tête Idempotency-Key obligatoire pour les mutations rejouables.
Dates au format RFC 3339 en UTC et identifiant de corrélation dans chaque réponse.
Pagination par curseur pour les collections ; aucune donnée biométrique brute dans l’API.

Accès non ouvert.

L’URL de base, le mécanisme d’émission des jetons, les scopes finaux et les quotas ne sont pas encore publiés. Aucun secret d’intégration ne sera livré dans cette documentation.

Cycle nominal

Créer et conclure une vérification

Créer un événement avec son contexte, sa fenêtre et le niveau demandé.
Ajouter les participants autorisés et activer l’événement.
Démarrer un round ; les applications réalisent les contrôles demandés.
Consulter un verdict factuel et les motifs de dégradation.
Clôturer l’événement puis demander un rapport et son paquet de preuve.

Exemple indicatifHTTP

POST /events
Authorization: Bearer <access_token>
Idempotency-Key: 7dd95eb4-5983-48c6-80bd-a7a857ba0e9a
Content-Type: application/json

{
  "context": "Comité de direction du 8 avril 2026",
  "assurance_level": "HIGH",
  "starts_at": "2026-04-08T08:00:00Z",
  "ends_at": "2026-04-08T10:00:00Z"
}

Les noms de champs et les valeurs peuvent encore évoluer avant la publication d’une spécification OpenAPI stable.

Ressources métier

Événements et participants

POST/events

Créer un événement borné.

GET/events/{event_id}

Lire le contexte et l’état courant.

PATCH/events/{event_id}

Modifier un brouillon avant activation.

POST/events/{event_id}/activate

Figer la politique applicable et ouvrir l’événement.

POST/events/{event_id}/participants

Inviter un participant selon les règles de minimisation.

GET/events/{event_id}/participants

Consulter les statuts factuels autorisés.

POST/events/{event_id}/complete

Clôturer l’événement et empêcher de nouveaux rounds.

Présence interactive

Rounds et challenges

POST/events/{event_id}/rounds

Démarrer un contrôle avec un nouveau contexte temporel.

POST/rounds/{round_id}/subjects/{subject_id}/ready

Confirmer que le sujet est prêt depuis son appareil lié.

GET/challenges/{challenge_id}

Obtenir le challenge destiné à l’appelant autorisé.

POST/challenges/{challenge_id}/observations/finalize

Finaliser une observation signée.

POST/rounds/{round_id}/finalize

Arrêter la collecte et calculer le résultat.

GET/rounds/{round_id}/verdict

Lire le niveau obtenu et les motifs associés.

Les frames brutes, secrets de challenge et paramètres antifraude ne sont pas exposés dans les API de gestion.

Preuve

Rapports et vérification

POST/events/{event_id}/reports

Produire un rapport à partir d’un événement clôturé.

GET/reports/{report_id}

Consulter les métadonnées et l’état de génération.

GET/reports/{report_id}/bundle

Télécharger le paquet de preuve autorisé.

POST/reports/verify

Vérifier l’intégrité et les signatures d’un paquet.

Une preuve n’est pas une décision métier.

L’API restitue les contrôles réalisés et leurs limites. L’intégrateur conserve la responsabilité de sa règle d’autorisation, de paiement ou de validation.

Contrats prévisibles

Statuts et erreurs

HTTP	Usage	Comportement attendu
`400`	Requête invalide	Corriger les champs signalés.
`401`	Authentification absente ou expirée	Obtenir un nouveau jeton.
`403`	Scope, rôle ou tenant insuffisant	Ne pas répéter sans changement d’autorisation.
`409`	État incompatible ou conflit d’idempotence	Relire la ressource avant une nouvelle action.
`422`	Règle métier non satisfaite	Présenter le motif sans transformer l’échec en succès.
`429`	Limite temporaire	Respecter `Retry-After` avec backoff.

Forme indicativeJSON

{
  "error": {
    "code": "EVENT_NOT_ACTIVE",
    "message": "L’événement n’est pas actif.",
    "correlation_id": "req_01J...",
    "retryable": false
  }
}