Avertissements et codes d'erreur de vérification NFC

Vue d’ensemble

Les avertissements du rapport NFC signalent chaque condition observée par Didit lors de la lecture et de la validation de la puce. Ils figurent dans le tableau warnings[] de chaque élément de nfc_verifications[] (voir le rapport NFC), avec feature défini sur "NFC". Chaque entrée suit la structure partagée de l’objet d’avertissement : feature, risk, additional_data, log_type, short_description, long_description, node_id. Chaque avertissement comporte trois niveaux :

Le code risk — un identifiant stable que vous pouvez utiliser pour effectuer des correspondances dans votre code (les codes répertoriés ci-dessous).
Le log_type — l’une des valeurs information, warning ou error. Il découle de l’action que votre workflow configure pour ce risque : Aucune action → information, Examen → warning, Refuser → error.
L’impact sur la décision — la même action configurée détermine également le status du rapport NFC : une action d’examen le fait passer à In Review, une action de refus à Declined.

Quatre risques NFC sont configurables de cette manière (SKIPPED_NFC_VALIDATION, NFC_CHIP_NOT_VERIFIED, NFC_TRUST_ANCHOR_MISSING, NFC_AND_OCR_DATA_NOT_SAME), ainsi que les cinq risques liés à la Japan My Number Card, chacun disposant de son propre paramètre. Les deux risques de certificat (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) sont uniquement informatifs : ils portent toujours la valeur log_type: "information" et ne modifient jamais le statut NFC à eux seuls. L’ensemble complet des codes de risque générés par le module NFC est présenté ci-dessous. Aucun autre code de risque NFC n’existe.

Avertissements générés

`risk`	Cause	Gravité (`log_type`)	Affecte le statut ?	Mesure corrective
`SKIPPED_NFC_VALIDATION`	La lecture de la puce a été ignorée : le workflow autorise l’omission (`allow_nfc_skip`) et l’utilisateur a appuyé sur ignorer, ou le client l’a ignorée car il ne pouvait pas lire le NFC. La raison exacte est enregistrée dans `additional_data.skip_reason` (voir Raisons de l’omission) et détermine le champ `long_description` de l’avertissement.	Suit le paramètre action d’omission du NFC (`skip_nfc_action`) : information / avertissement / erreur.	Configurable : No action, Review ou Decline.	Si votre politique exige le NFC, définissez l’action en cas d’omission sur Decline (ou interdisez totalement l’omission) et invitez l’utilisateur à réessayer depuis un appareil compatible NFC. Sinon, laissez-la sur No action pour basculer vers une vérification par OCR uniquement.
`NFC_CHIP_NOT_VERIFIED`	La puce a été lue mais a échoué à la vérification cryptographique pour une raison autre qu’une ancre de confiance manquante explicitement identifiée. Un hachage de groupe de données, la signature SOD ou un autre contrôle d’authentification passive n’a pas pu être vérifié.	Suit le paramètre action en cas de puce non vérifiée (`unverified_chip_action`).	Configurable : No action, Review ou Decline.	Considérez ceci comme une puce potentiellement invalide ou altérée. Inspectez `authenticity` et `certificate_summary.validation` pour voir quel contrôle a échoué.
`NFC_TRUST_ANCHOR_MISSING`	Le certificat du signataire du document (DSC) de la puce appartient à une génération d’autorité de certification de signature du pays (CSCA) non disponible dans le magasin de confiance de Didit (`certificate_summary.validation.csca_missing` vaut `true`). Didit ne peut donc pas établir la chaîne de confiance du SOD.	Suit le paramètre action en cas de puce non vérifiée (`unverified_chip_action`).	Configurable : No action, Review ou Decline.	Il s’agit d’un manque de couverture du magasin de confiance, et non d’une preuve d’altération de la puce. Examinez le document à l’aide de vos contrôles de repli et contactez le support Didit en indiquant le pays de délivrance afin que la CSCA manquante puisse être examinée.
`NFC_AND_OCR_DATA_NOT_SAME`	La MRZ lue depuis la puce ne correspond pas à la MRZ obtenue par OCR à partir du côté visible du document (comparée après normalisation, en ignorant les caractères de remplissage `<`). Signal fort de falsification.	Suit le paramètre action en cas d’incohérence des données (`inconsistent_data_action`) — le même paramètre qui régit les contrôles de cohérence des données de vérification d’identité.	Configurable : No action, Review ou Decline.	À traiter comme une falsification sauf preuve du contraire ; Decline est le paramètre habituel. Le payload `additional_data` comprend les lignes de la MRZ lue par OCR (`ocr_mrz`, tableau) et la MRZ de la puce (`nfc_mrz`, chaîne unique) pour une comparaison manuelle.
`DSC_CERTIFICATE_REVOKED`	Le certificat du signataire du document qui a signé cette puce apparaît dans la liste de révocation de certificats (CRL) du pays de délivrance.	Toujours `information`.	Non — ne modifie jamais le statut NFC à lui seul.	Signal fort indiquant que la clé de signature a pu être compromise ; orientez ces sessions vers un examen manuel via votre propre logique si nécessaire. Notez que la puce déclenchera généralement aussi `NFC_CHIP_NOT_VERIFIED`, qui est configurable.
`DSC_CERTIFICATE_EXPIRED`	La période de validité du DSC a expiré (`certificate_summary.validation.dsc_expired` vaut `true`).	Toujours `information`.	Non — ne modifie jamais le statut NFC à lui seul.	Fréquent pour les documents anciens. Comme pour la révocation, un DSC expiré échoue également à la validation complète du SOD, de sorte que `NFC_CHIP_NOT_VERIFIED` se déclenche en parallèle et applique l’action que vous avez configurée.
`JPKI_CERTIFICATE_INVALID`	Japan My Number Card : un certificat lu depuis la carte ne remonte pas à l’autorité de certification JPKI de son type, se situe en dehors de sa période de validité ou n’est pas un certificat My Number Card de ce type. `additional_data.certificate_types` liste les certificats qui ont échoué ; `jpki.certificates[].failure` en indique la raison.	Suit `jpki_certificate_invalid_action` (Decline par défaut).	Configurable : No action, Review ou Decline.	Considérez la carte comme invalide ou altérée. Un certificat de carte expiré aboutit également ici : le titulaire doit le renouveler auprès de sa municipalité.
`JPKI_SIGNATURE_INVALID`	Japan My Number Card : la signature de la carte sur le défi à usage unique ne peut pas être vérifiée à l’aide de son certificat, de sorte que la possession de la carte et la connaissance de son code PIN ne sont pas prouvées. Déclenché également lorsque l’étape NFC s’est terminée sans aucune lecture de carte (`additional_data.certificate_types` est alors vide).	Suit `jpki_signature_invalid_action` (Decline par défaut).	Configurable : No action, Review ou Decline.	N’acceptez pas la lecture de la carte comme preuve. Demandez à la personne de réessayer avec la carte physique.
`JPKI_CERTIFICATE_REVOKED`	Japan My Number Card : la vérification de révocation indique qu’un certificat est révoqué, par exemple parce que la carte a été signalée comme perdue ou que l’enregistrement du titulaire a changé (`jpki.revocation_status` vaut `revoked`).	Suit `jpki_certificate_revoked_action` (Decline par défaut).	Configurable : No action, Review ou Decline.	N’acceptez pas la carte.
`JPKI_REVOCATION_UNCHECKED`	Japan My Number Card : les certificats et la signature ont été vérifiés, mais aucune réponse de révocation n’était disponible (`jpki.revocation_status` vaut `unchecked`), on ne peut donc pas exclure qu’il s’agisse d’une carte révoquée. Non déclenché si la chaîne ou la signature a déjà échoué.	Suit `jpki_revocation_unchecked_action` (Review par défaut).	Configurable : No action, Review ou Decline.	Déterminez l’importance qu’a pour vous une carte vérifiée sans réponse de révocation, et configurez l’action en conséquence.
`JPKI_AND_OCR_DATA_NOT_SAME`	Japan My Number Card : le nom, la date de naissance, le sexe ou l’adresse figurant dans le certificat de signature diffère des données lues à partir de la photo de la même carte. `additional_data.fields` nomme les attributs qui diffèrent, jamais leurs valeurs.	Suit `jpki_inconsistent_data_action` (Review par défaut).	Configurable : No action, Review ou Decline.	Comparez `jpki.attributes` avec les données de vérification d’identité avant de décider. Un nom comportant un caractère rare peut différer car le certificat contient un caractère de substitution (`jpki.attributes.name_substitute_characters`).

SKIPPED_NFC_VALIDATION est mutuellement exclusif avec NFC_CHIP_NOT_VERIFIED et NFC_TRUST_ANCHOR_MISSING : les avertissements de vérification de puce ne sont évalués que lorsque la lecture de la puce n’a pas été ignorée. Les deux avertissements de vérification de puce sont également mutuellement exclusifs.

Chaînes de description exactes

L’API renvoie ces chaînes short_description et long_description exactes pour chaque risque :

`risk`	`short_description`	`long_description`
`SKIPPED_NFC_VALIDATION`	Validation NFC ignorée	Spécifique à la raison — voir Raisons d’omission. Revient par défaut à « The Near Field Communication (NFC) chip validation process was not completed, potentially due to technical issues or lack of NFC support. » pour les sessions historiques enregistrées avant l’existence des motifs d’omission.
`NFC_CHIP_NOT_VERIFIED`	Puce NFC non vérifiée	La puce NFC (Near Field Communication) a échoué à l’authentification passive pour une raison autre qu’une ancre de confiance manquante explicitement identifiée. Les données ou la signature de la puce pourraient être invalides ou altérées.
`NFC_TRUST_ANCHOR_MISSING`	Ancre de confiance NFC non disponible	La puce NFC (Near Field Communication) n’a pas pu être vérifiée car l’ancre de confiance de l’autorité de certification de signature du pays (CSCA) du pays de délivrance n’est pas disponible. Il s’agit d’une lacune de couverture du magasin de confiance et non d’une preuve d’altération de la puce.
`NFC_AND_OCR_DATA_NOT_SAME`	Données NFC et OCR non identiques	Les données de la puce NFC (Near Field Communication) et les données de l’OCR ne correspondent pas, ce qui indique une altération potentielle du document ou une incohérence des données.
`DSC_CERTIFICATE_REVOKED`	Certificat du signataire du document révoqué	Le certificat du signataire du document (DSC) utilisé pour signer les données de la puce du passeport électronique a été révoqué par la liste de révocation de certificats (CRL) du pays de délivrance, ce qui indique que la clé de signature a pu être compromise.
`DSC_CERTIFICATE_EXPIRED`	Certificat du signataire du document expiré	Le certificat du signataire du document (DSC) utilisé pour signer les données de la puce du passeport électronique a expiré, ce qui signifie que la période de validité du certificat est dépassée.
`JPKI_CERTIFICATE_INVALID`	Certificat de la carte My Number non valide	Un certificat lu depuis la puce de la carte My Number n’est pas valide : il ne remonte pas jusqu’à l’autorité de certification de l’infrastructure à clés publiques japonaise (JPKI), il se situe en dehors de sa période de validité ou il ne s’agit pas d’un certificat de carte My Number du type requis.
`JPKI_SIGNATURE_INVALID`	Signature de la carte My Number non valide	La signature créée par la carte My Number sur le défi de vérification à usage unique ne peut pas être vérifiée à l’aide du certificat de la carte, la possession de la carte et la connaissance de son code PIN ne sont donc pas prouvées.
`JPKI_CERTIFICATE_REVOKED`	Certificat de la carte My Number révoqué	La vérification de la révocation indique qu’un certificat lu depuis la carte My Number a été révoqué, par exemple parce que la carte a été signalée perdue ou que l’enregistrement du titulaire a été modifié.
`JPKI_REVOCATION_UNCHECKED`	Statut de révocation de la carte My Number non vérifié	Le certificat et la signature de la carte My Number ont été vérifiés, mais son statut de révocation n’a pas pu être contrôlé, une carte révoquée ne peut donc pas être exclue.
`JPKI_AND_OCR_DATA_NOT_SAME`	Données de puce et OCR de la carte My Number non identiques	Le nom, la date de naissance, le sexe ou l’adresse figurant dans le certificat de signature de la carte My Number ne correspondent pas aux données lues sur l’image de la carte (OCR), ce qui indique une possible substitution ou une incohérence des données.

Motifs d’omission

Les avertissements SKIPPED_NFC_VALIDATION comportent additional_data.skip_reason, l’un des sept codes stables indiquant précisément pourquoi le NFC n’a pas été exécuté (sur les sessions enregistrées avant l’introduction des motifs d’omission, additional_data peut être null — traitez ce champ comme facultatif lors du traitement des décisions historiques). La même taxonomie apparaît au niveau de la session sous le champ nfc_skip_reason dans le payload de décision — y compris pour les sessions où le NFC ne pouvait pas du tout être exécuté (document sans puce, intégration web) et pour lesquelles aucun rapport ou avertissement NFC n’existe donc.

`skip_reason`	Signification	`long_description`
`USER_SKIPPED`	Le NFC a été proposé sur un appareil compatible et l’utilisateur a choisi de l’ignorer.	L’étape de lecture de la puce NFC a été proposée sur un appareil compatible, mais l’utilisateur a choisi de l’ignorer (l’omission est autorisée par la configuration du workflow).
`DOCUMENT_WITHOUT_CHIP`	La conception du document ne comporte aucune puce NFC lisible (il ne s’agit pas d’un document électronique ICAO 9303).	La vérification NFC n’a pas pu être effectuée, car ce document ne comporte pas de puce NFC lisible : il ne s’agit pas d’un document électronique ICAO 9303.
`CHIP_CERTIFICATE_UNAVAILABLE`	La puce existe, mais aucun certificat de signature du pays de délivrance (CSCA) ne couvre la période de délivrance du document, la signature ne peut donc pas être vérifiée.	La vérification NFC n’a pas pu être effectuée, car le certificat de signature (CSCA) du pays de délivrance couvrant la période de délivrance de ce document n’est pas disponible ; la signature de la puce ne peut donc pas être vérifiée.
`DEVICE_WITHOUT_NFC`	Un SDK natif a signalé que le téléphone ne dispose d’aucun lecteur NFC disponible.	La vérification NFC n’a pas pu être effectuée, car l’appareil de l’utilisateur a signalé qu’il ne disposait d’aucun lecteur NFC.
`INTEGRATION_WITHOUT_NFC_ACCESS`	La vérification s’est exécutée sans SDK natif (par exemple dans un navigateur web), qui n’a pas accès au lecteur NFC du téléphone.	La vérification NFC n’a pas pu être effectuée, car elle ne s’est pas déroulée via un SDK mobile natif ; le lecteur NFC du téléphone n’était donc pas accessible (les navigateurs web ne peuvent pas lire les puces NFC).
`MRZ_KEY_UNAVAILABLE`	La clé d’accès à la puce (graine BAC/PACE) n’a pas pu être dérivée de la MRZ du document.	La vérification NFC n’a pas pu être effectuée, car la clé d’accès à la puce n’a pas pu être dérivée de la zone lisible par machine (MRZ) du document.
`JPKI_UNAVAILABLE`	Le document est une Japan My Number Card, dont la puce est lue via JPKI, et JPKI n’était pas disponible pour cette vérification : elle n’est pas activée, ou la version du SDK natif de l’application ne peut pas lire les My Number Cards. Une My Number Card vérifiée dans un navigateur reçoit `INTEGRATION_WITHOUT_NFC_ACCESS`, et sur un téléphone sans NFC, elle reçoit `DEVICE_WITHOUT_NFC`, comme pour toute puce.	La vérification NFC n’a pas pu être effectuée, car cette My Number Card est lue via JPKI, qui n’était pas disponible pour cette vérification : JPKI n’est pas activé ou le SDK de l’application ne peut pas lire les My Number Cards.

Un rapport NFC et son avertissement SKIPPED_NFC_VALIDATION n’existent que lorsque le client a atteint l’étape NFC et l’a explicitement ignorée (généralement USER_SKIPPED, ou DEVICE_WITHOUT_NFC lorsque le lecteur s’est avéré indisponible au moment de la numérisation). Lorsque l’étape NFC a été contournée avant même de pouvoir être proposée — document sans puce, certificat manquant, aucune fonctionnalité NFC signalée, clé MRZ illisible, JPKI indisponible — aucun rapport ni avertissement n’est créé et le motif n’apparaît que dans le champ nfc_skip_reason au niveau de la session, sans affecter le statut de la session.

Configuration

Trois paramètres de workflow contrôlent le routage des avertissements NFC. Chacun peut être défini sur Aucune action, Examen, ou Refuser :

Action d’omission NFC (skip_nfc_action) — s’applique à SKIPPED_NFC_VALIDATION. L’omission n’est proposée aux utilisateurs que lorsque allow_nfc_skip est activé.
Action de puce non vérifiée (unverified_chip_action) — s’applique à la fois à NFC_CHIP_NOT_VERIFIED et à NFC_TRUST_ANCHOR_MISSING, de sorte que le comportement du statut de session reste le même tandis que le code de risque explique pourquoi la vérification a échoué.
Action d’incohérence des données (inconsistent_data_action) — s’applique à NFC_AND_OCR_DATA_NOT_SAME. Il s’agit du même paramètre d’incohérence des données que celui utilisé par la vérification d’identité.

Les deux risques DSC_CERTIFICATE_* n’ont pas de paramètre d’action — ils sont toujours à titre informatif. Les risques liés à la Japan My Number Card comportent cinq paramètres supplémentaires, répertoriés dans la section suivante.

Japan My Number Card (JPKI)

Une Japan My Number Card est lue via JPKI au lieu de l’ICAO 9303 (chip_protocol: "jpki"), de sorte que les risques ICAO ci-dessus ne se déclenchent jamais pour celle-ci. Sa lecture génère plutôt ces cinq risques, chacun ayant son propre paramètre sur le nœud NFC :

Paramètre	Risque	Par défaut
`jpki_certificate_invalid_action`	`JPKI_CERTIFICATE_INVALID`	Refuser
`jpki_signature_invalid_action`	`JPKI_SIGNATURE_INVALID`	Refuser
`jpki_certificate_revoked_action`	`JPKI_CERTIFICATE_REVOKED`	Refuser
`jpki_revocation_unchecked_action`	`JPKI_REVOCATION_UNCHECKED`	Examen
`jpki_inconsistent_data_action`	`JPKI_AND_OCR_DATA_NOT_SAME`	Examen

Une lecture de My Number Card ignorée génère SKIPPED_NFC_VALIDATION et suit skip_nfc_action, comme pour toute puce. Consultez Japan My Number Card (JPKI) pour savoir comment fonctionne la lecture.

La lecture de la My Number Card via JPKI n’est pas encore activée en production. Tant qu’elle ne l’est pas, une My Number Card ignore l’étape NFC avec le motif d’omission JPKI_UNAVAILABLE et aucun de ces risques n’est généré.

Exemples

In Review — la puce n’a pas pu être vérifiée

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "NFC_CHIP_NOT_VERIFIED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "NFC chip not verified",
    "long_description": "The Near Field Communication (NFC) chip failed passive authentication for a reason other than an explicitly identified missing trust anchor. The chip data or signature could be invalid or altered.",
    "node_id": "nfc_primary"
  },
  {
    "feature": "NFC",
    "risk": "DSC_CERTIFICATE_EXPIRED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Document Signer Certificate expired",
    "long_description": "The Document Signer Certificate (DSC) used to sign the ePassport chip data has expired, meaning the certificate's validity period has passed.",
    "node_id": "nfc_primary"
  }
]
}

Ici, l’action pour puce non vérifiée est configurée sur Review, donc NFC_CHIP_NOT_VERIFIED porte log_type: "warning" et le statut du rapport NFC est In Review. L’entrée pour DSC expirée est purement informative.

Declined — incohérence puce / OCR

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "NFC_AND_OCR_DATA_NOT_SAME",
    "additional_data": {
      "ocr_mrz": ["P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<", "AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04"],
      "nfc_mrz": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06"
    },
    "log_type": "error",
    "short_description": "NFC and OCR data not same",
    "long_description": "The Near Field Communication (NFC) chip data and the OCR data don't match, indicating potential document tampering or data inconsistency.",
    "node_id": "nfc_primary"
  }
]
}

Ici, l’action pour incohérence des données est configurée sur Decline, donc l’avertissement porte log_type: "error" et le statut du rapport NFC est Declined. Notez que ocr_mrz est un tableau de lignes MRZ tandis que nfc_mrz est la chaîne MRZ unique et concaténée de la puce.

In Review : My Number Card sans réponse de révocation

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "JPKI_REVOCATION_UNCHECKED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "My Number Card revocation status not checked",
    "long_description": "The certificate and signature of the My Number Card were verified, but its revocation status could not be checked, so a revoked card cannot be ruled out.",
    "node_id": "nfc_primary"
  }
]
}

Ici, jpki_revocation_unchecked_action conserve sa valeur par défaut, Review, donc l’avertissement porte log_type: "warning" et le statut du rapport NFC est In Review. La carte elle-même a été authentifiée : jpki.chain_valid et jpki.signature_valid sont tous deux à true.

Types d’avertissement

Une gravité est attribuée à chaque risque selon la configuration de votre application. Les trois niveaux de gravité sont :

Voir aussi

Rapport NFC — schéma complet du rapport et statuts.
Webhooks — status.updated se déclenche lors des changements de statut de session ; le payload de décision (incluant les avertissements NFC) est joint lorsque la session atteint Approved, Declined, In Review ou Abandoned.
Modèles de données — Vérification NFC — schéma canonique champ par champ.
Modèles de données — Objet Warning — structure de chaque entrée dans warnings[].

Authentification

Vérification

Surveillance

Plateforme

Avertissements et codes d'erreur de vérification NFC

Vue d’ensemble

Avertissements générés

Chaînes de description exactes

Motifs d’omission

Configuration

Japan My Number Card (JPKI)

Exemples

In Review — la puce n’a pas pu être vérifiée

Declined — incohérence puce / OCR

In Review : My Number Card sans réponse de révocation

Types d’avertissement

Voir aussi

​Vue d’ensemble

​Avertissements générés

​Chaînes de description exactes

​Motifs d’omission

​Configuration

​Japan My Number Card (JPKI)

​Exemples

​In Review — la puce n’a pas pu être vérifiée

​Declined — incohérence puce / OCR

​In Review : My Number Card sans réponse de révocation

​Types d’avertissement

​Voir aussi

Vue d’ensemble

Avertissements générés

Chaînes de description exactes

Motifs d’omission

Configuration

Japan My Number Card (JPKI)

Exemples

In Review — la puce n’a pas pu être vérifiée

Declined — incohérence puce / OCR

In Review : My Number Card sans réponse de révocation

Types d’avertissement

Voir aussi