Rapport d'authentification biométrique : schéma JSON

Le rapport d’authentification biométrique décrit comment Didit rend compte de la revérification d’un utilisateur récurrent. Le workflow exécute une nouvelle vérification de détection du vivant et, lorsque la correspondance faciale est activée dans le workflow, une correspondance faciale 1:1 par rapport au visage de référence résolu lors de la création de la session (le portrait_image que vous avez fourni, ou le visage enregistré de l’utilisateur recherché via vendor_data). Les deux vérifications apparaissent comme des éléments de fonctionnalité standard dans la réponse de décision de session V3.

Rapport d'authentification biométrique Didit combinant la détection du vivant et la correspondance faciale avec un portrait enregistré

Vue d’ensemble

L’authentification biométrique est un type de workflow (workflow_type: "biometric_authentication"), et non un objet de réponse distinct. Lorsque le workflow s’exécute, il émet :

Une détection du vivant qui capture un selfie en direct et lui attribue un score d’usurpation.
Une correspondance faciale comparant le visage capturé au visage de référence résolu lors de la création de la session (uniquement lorsque la correspondance faciale est activée dans le workflow).

Dès que le workflow inclut la correspondance faciale, la création de session nécessite un visage de référence. Envoyez portrait_image (image encodée en base64, 2MB max.), ou omettez-le et Didit réutilise le visage déjà stocké pour l’utilisateur identifié par vendor_data : d’abord un visage issu d’une détection du vivant approuvée, puis la photo de la puce du passeport électronique, puis le portrait de la pièce d’identité, puis un visage de profil enrôlé manuellement. Si ni portrait_image ni un visage enregistré n’est disponible, la création de session renvoie 400 avec

{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}

. Dans les deux cas, la référence résolue est enregistrée sous la nouvelle session, de sorte que le champ source_image_session_id de l’élément de correspondance faciale est défini sur le session_id propre à cette session (cela indique que la référence provient du portrait enregistré de la session plutôt que d’un portrait de document capturé au cours de la même session, ce qui laisserait le champ à null).

Où il apparaît

Clé de réponse de décision	Pluriel	Schéma de l’élément
`liveness_checks[]`	Un par étape de détection du vivant (généralement 1 dans l’authentification biométrique)	data-models#liveness-check
`face_matches[]`	Un par étape de correspondance faciale (`null` dans les workflows de détection du vivant uniquement)	data-models#face-match

Les deux tableaux sont renvoyés par GET /v3/session/{sessionId}/decision/ pour les sessions dont le type de workflow est biometric_authentication. Il s’agit toujours de tableaux — jamais d’objets uniques — et chacun reste null jusqu’à ce que son étape ait produit des données. Chaque élément comporte un node_id afin que les workflows multi-instances puissent lever toute ambiguïté sur les étapes.

Référence du schéma

La liste complète des champs est définie une seule fois sur la page des modèles de données, de sorte que chaque rapport exposant ces fonctionnalités partage une source unique de vérité :

Schéma d’élément de détection du vivant — status, method, score, reference_image, video_url, age_estimation, matches[], face_quality, face_luminance, warnings[], node_id.
Schéma d’élément de correspondance faciale — status, score, source_image_session_id, source_image, target_image, warnings[], node_id.
Format de l’entrée d’avertissement — feature, risk, additional_data, log_type, short_description, long_description, node_id.

Valeurs de statut

liveness_checks[].status et face_matches[].status utilisent tous deux le cycle de vie partagé des fonctionnalités (statuts au niveau de la fonctionnalité) :

Statut	Signification
`Not Finished`	L’étape n’a pas encore produit de résultat final (l’utilisateur ne l’a pas terminée, ou a abandonné). Avant même qu’une étape ne commence, son tableau est simplement `null` dans la réponse de décision.
`Approved`	La vérification a passé tous les seuils configurés.
`In Review`	Le score s’est situé dans la plage d’examen, ou un avertissement configurable a été paramétré pour entraîner un examen.
`Declined`	Le score s’est situé au niveau ou en dessous du seuil de refus, ou un avertissement de refus automatique s’est déclenché (attaque faciale, aucun visage détecté, visage sur liste de blocage, aucune image de référence pour la correspondance faciale).
`Resub Requested`	Un réviseur a demandé à l’utilisateur de réessayer cette étape.

Le status global de la session agrège les deux éléments : toute fonctionnalité en Declined entraîne le refus de la session, toute fonctionnalité en In Review place la session en In Review, sinon Approved (une fois que chaque fonctionnalité est terminée). Pour le comportement des seuils et la liste complète des codes d’avertissement, consultez Avertissements d’authentification biométrique.

Exemple — détection du vivant + correspondance faciale (approuvé)

Les exemples sont abrégés : l’enveloppe de décision complète contient également session_url, metadata, callback, reviews, contact_details, expected_details, environment, created_at et expires_at.

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "session_number": 1234,
  "status": "Approved",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "features": ["LIVENESS", "FACE_MATCH"],
  "vendor_data": "user-123",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 92.4,
      "face_luminance": 58.1,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Approved",
      "score": 88.47,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": []
    }
  ],
  "id_verifications": null,
  "nfc_verifications": null,
  "poa_verifications": null,
  "phone_verifications": null,
  "email_verifications": null,
  "aml_screenings": null
}

Exemple — détection du vivant uniquement (la correspondance faciale est désactivée dans le workflow)

{
  "session_id": "22222222-3333-4444-5555-666666666666",
  "session_kind": "user",
  "status": "Approved",
  "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb",
  "features": ["LIVENESS"],
  "vendor_data": "user-456",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "ACTIVE_3D",
      "score": 96.10,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": []
    }
  ],
  "face_matches": null
}

Le mode détection du vivant uniquement est une configuration de workflow : lorsque la correspondance faciale est désactivée, aucun visage de référence n’est requis lors de la création de la session et face_matches reste null. Lorsque la correspondance faciale est activée, l’omission de portrait_image ne bascule pas vers le mode détection du vivant uniquement : Didit réutilise le visage stocké pour l’utilisateur identifié par vendor_data, et si aucun visage stocké n’existe, la création de session échoue avec une erreur 400.

Exemple — correspondance faciale refusée en raison d’une faible similarité

{
  "session_id": "33333333-4444-5555-6666-777777777777",
  "status": "Declined",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 91.20,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 90.15,
      "face_luminance": 55.30,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Declined",
      "score": 41.18,
      "source_image_session_id": "33333333-4444-5555-6666-777777777777",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match"
        }
      ]
    }
  ]
}

Note de sécurité

reference_image, video_url, source_image et target_image sont des URL signées qui expirent après une fenêtre de validité limitée (4 heures par défaut). Elles pointent vers des données biométriques — ne les mettez pas en cache et ne les exposez pas publiquement. Stockez le résultat de la vérification (statut, score, source_image_session_id) de votre côté ; appelez à nouveau l’endpoint de décision si vous avez besoin d’URL actualisées.

Voir aussi

Avertissements d'authentification biométrique

Codes d’avertissement, seuils et conditions de refus automatique.

Rapport de détection du vivant

Référence complète des champs pour les éléments de liveness_checks[].

Rapport de correspondance faciale

Référence complète des champs pour les éléments de face_matches[].

Authentification

Vérification

Surveillance

Plateforme

Rapport d'authentification biométrique : schéma JSON

Vue d’ensemble

Où il apparaît

Référence du schéma

Valeurs de statut

Exemple — détection du vivant + correspondance faciale (approuvé)

Exemple — détection du vivant uniquement (la correspondance faciale est désactivée dans le workflow)

Exemple — correspondance faciale refusée en raison d’une faible similarité

Note de sécurité

Voir aussi

Avertissements d'authentification biométrique

Rapport de détection du vivant

Rapport de correspondance faciale

​Vue d’ensemble

​Où il apparaît

​Référence du schéma

​Valeurs de statut

​Exemple — détection du vivant + correspondance faciale (approuvé)

​Exemple — détection du vivant uniquement (la correspondance faciale est désactivée dans le workflow)

​Exemple — correspondance faciale refusée en raison d’une faible similarité

​Note de sécurité

​Voir aussi

Avertissements d'authentification biométrique

Rapport de détection du vivant

Rapport de correspondance faciale

Vue d’ensemble

Où il apparaît

Référence du schéma

Valeurs de statut

Exemple — détection du vivant + correspondance faciale (approuvé)

Exemple — détection du vivant uniquement (la correspondance faciale est désactivée dans le workflow)

Exemple — correspondance faciale refusée en raison d’une faible similarité

Note de sécurité

Voir aussi