Informe d'autenticació biomètrica: esquema JSON

L’informe d’Autenticació biomètrica és la manera com Didit comunica la reverificació d’un usuari recurrent. El flux de treball executa una nova prova de vida i, quan la coincidència facial està activada al flux de treball, una coincidència facial 1:1 respecte a la cara de referència resolta en crear la sessió (la portrait_image que has proporcionat, o la cara emmagatzemada de l’usuari cercada mitjançant vendor_data). Ambdues comprovacions apareixen com a elements de funcionalitat estàndard a la resposta de decisió de la sessió V3.

Informe d'autenticació biomètrica de Didit que combina la prova de vida i la coincidència facial respecte a un retrat emmagatzemat

Visió general

L’autenticació biomètrica és un tipus de flux de treball (workflow_type: "biometric_authentication"), no un objecte de resposta independent. Quan el flux de treball s’executa, emet:

Una prova de vida que captura una selfie en viu i li assigna una puntuació de suplantació.
Una coincidència facial que compara la cara capturada amb la cara de referència resolta en crear la sessió (només quan la coincidència facial està activada al flux de treball).

Sempre que el flux de treball inclou la coincidència facial, la creació de la sessió necessita una cara de referència. Envia portrait_image (imatge codificada en base64, màxim 2 MB), o omet-la i Didit reutilitzarà la cara ja emmagatzemada per a l’usuari de vendor_data: primer, una cara d’una prova de vida aprovada, després la foto del xip de l’ePassport, després el retrat del document d’identitat i, finalment, una cara de perfil registrada manualment. Si ni portrait_image ni una cara emmagatzemada estan disponibles, la creació de la sessió retorna un error 400 amb

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

. En tots dos casos, la referència resolta es registra sota la nova sessió, de manera que el camp source_image_session_id de l’element de coincidència facial s’estableix amb el mateix session_id d’aquesta sessió (això t’indica que la referència prové del retrat emmagatzemat de la sessió i no pas d’un retrat de document capturat a la mateixa sessió, cosa que deixaria el camp com a null).

On apareix

Clau de resposta de decisió	Plural	Esquema de l’element
`liveness_checks[]`	Un per pas de prova de vida (normalment 1 en autenticació biomètrica)	data-models#liveness-check
`face_matches[]`	Un per pas de coincidència facial (`null` en fluxos de treball que només inclouen la prova de vida)	data-models#face-match

GET /v3/session/{sessionId}/decision/ retorna ambdues matrius per a les sessions el tipus de flux de treball de les quals és biometric_authentication. Sempre són matrius —mai objectes individuals— i cadascuna és null fins que el seu pas corresponent ha generat dades. Cada element inclou un node_id perquè els fluxos de treball amb múltiples instàncies puguin desambiguar els passos.

Referència de l’esquema

La llista completa de camps es defineix un sol cop a la pàgina de models de dades perquè tots els informes que mostren aquestes funcionalitats comparteixin una única font d’informació:

Esquema de l’element de prova de vida — status, method, score, reference_image, video_url, age_estimation, matches[], face_quality, face_luminance, warnings[], node_id.
Esquema de l’element de coincidència facial — status, score, source_image_session_id, source_image, target_image, warnings[], node_id.
Format de l’entrada d’advertència — feature, risk, additional_data, log_type, short_description, long_description, node_id.

Valors d’estat

Tant liveness_checks[].status com face_matches[].status utilitzen el cicle de vida compartit de les funcionalitats (estats a nivell de funcionalitat):

Estat	Significat
`Not Finished`	El pas encara no ha generat un resultat final (l’usuari no l’ha completat o hi ha hagut abandonament). Abans que un pas s’iniciï, la seva matriu és simplement `null` a la resposta de decisió.
`Approved`	La comprovació ha superat tots els llindars configurats.
`In Review`	La puntuació ha caigut a la franja de revisió, o bé una advertència configurable s’ha establert en revisió.
`Declined`	La puntuació ha caigut en el llindar de rebuig o per sota d’aquest, o s’ha activat una advertència de rebuig automàtic (atac facial, no s’ha detectat cap cara, cara a la llista de bloqueig, sense imatge de referència per a la coincidència facial).
`Resub Requested`	Un revisor ha sol·licitat a l’usuari que reintenti aquest pas.

L’status global de la sessió agrega ambdós elements: qualsevol funcionalitat en Declined fa que es rebutgi la sessió, qualsevol en In Review la posa en revisió (In Review), i en cas contrari queda aprovada (Approved) (un cop finalitzades totes les funcionalitats). Per conèixer el comportament dels llindars i la llista completa de codis d’advertència, consulta Advertències d’autenticació biomètrica.

Exemple — prova de vida + coincidència facial (aprovada)

Els exemples estan abreujats: l’embolcall complet de la decisió també inclou session_url, metadata, callback, reviews, contact_details, expected_details, environment, created_at i 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 — només prova de vida (Coincidència facial desactivada al flux de treball)

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

El mode que només inclou la prova de vida és una configuració del flux de treball: quan la coincidència facial està desactivada, no es requereix cap cara de referència en crear la sessió i face_matches es manté com a null. Quan la coincidència facial està activada, ometre portrait_image no fa passar al mode que només inclou la prova de vida: Didit reutilitza la cara emmagatzemada per a l’usuari de vendor_data, i si no n’hi ha cap d’emmagatzemada, la creació de la sessió falla amb un error 400.

Exemple — coincidència facial rebutjada per baixa similitud

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

Nota de seguretat

reference_image, video_url, source_image i target_image són URL signades que caduquen després d’un període de validesa limitat (4 hores per defecte). Apunten a dades biomètriques; no les emmagatzemis en memòria cau ni les exposis públicament. Guarda el resultat de la verificació (estat, puntuació, source_image_session_id) al teu sistema; torna a consultar l’endpoint de decisió si necessites URL noves.

Relacionat

Advertències d'autenticació biomètrica

Codis d’advertència, llindars i condicions de rebuig automàtic.

Informe de prova de vida

Referència completa de camps per als elements de liveness_checks[].

Informe de coincidència facial

Referència completa de camps per als elements de face_matches[].

Autenticació

Verificació

Monitoratge

Plataforma

Informe d'autenticació biomètrica: esquema JSON

Visió general

On apareix

Referència de l’esquema

Valors d’estat

Exemple — prova de vida + coincidència facial (aprovada)

Exemple — només prova de vida (Coincidència facial desactivada al flux de treball)

Exemple — coincidència facial rebutjada per baixa similitud

Nota de seguretat

Relacionat

Advertències d'autenticació biomètrica

Informe de prova de vida

Informe de coincidència facial

​Visió general

​On apareix

​Referència de l’esquema

​Valors d’estat

​Exemple — prova de vida + coincidència facial (aprovada)

​Exemple — només prova de vida (Coincidència facial desactivada al flux de treball)

​Exemple — coincidència facial rebutjada per baixa similitud

​Nota de seguretat

​Relacionat

Advertències d'autenticació biomètrica

Informe de prova de vida

Informe de coincidència facial

Visió general

On apareix

Referència de l’esquema

Valors d’estat

Exemple — prova de vida + coincidència facial (aprovada)

Exemple — només prova de vida (Coincidència facial desactivada al flux de treball)

Exemple — coincidència facial rebutjada per baixa similitud

Nota de seguretat

Relacionat