Rapport de vérification NFC : puce et authenticité

Vue d’ensemble

Le rapport de vérification NFC consigne ce que Didit a lu et validé à partir de la puce NFC d’un document — un passeport électronique, une carte d’identité électronique ou un autre document électronique ICAO 9303. Il comprend les données biographiques de la puce, les contrôles d’intégrité cryptographique (hachages du SOD et des Data Groups), ainsi qu’un résumé du Document Signer Certificate (DSC) utilisé par le pays de délivrance. Le rapport est généré une fois que l’utilisateur a terminé l’étape NFC dans un workflow. Didit lit les Data Groups de la puce sur l’appareil de l’utilisateur, vérifie la signature du Document Security Object (SOD) par rapport au certificat CSCA du pays de délivrance, compare le hachage de chaque Data Group aux valeurs signées par le SOD, et procède à un recoupement entre la MRZ de la puce et la MRZ lue par OCR sur la face visible du document. Une carte japonaise My Number Card est lue via JPKI à la place (chip_protocol: "jpki") : son rapport contient les vérifications du certificat, de la signature, de la révocation et des données du titulaire sous jpki, et les champs ICAO restent null. Voir Japan My Number Card (JPKI). Chaque rapport comporte son propre status — indépendant du statut global de la session — qui reflète la manière dont l’étape NFC seule s’est conclue :

Approuvé — la puce a été lue et aucun des avertissements déclenchés n’est configuré pour orienter l’étape vers un examen ou un refus.
En cours d’examen — au moins un avertissement s’est déclenché dont l’action configurée est Examen (par exemple NFC_CHIP_NOT_VERIFIED ou NFC_TRUST_ANCHOR_MISSING lorsque l’action pour puce non vérifiée est définie sur Examen, ou JPKI_REVOCATION_UNCHECKED avec son action par défaut).
Refusé — au moins un avertissement s’est déclenché dont l’action configurée est Refuser (par exemple NFC_AND_OCR_DATA_NOT_SAME lorsque l’action en cas d’incohérence de données est définie sur Refuser).
Non terminé — l’utilisateur n’a jamais terminé l’étape NFC ; la lecture de la puce a été abandonnée ou l’appareil ne prenait pas en charge le NFC.
Nouvelle soumission demandée — un réviseur a demandé à l’utilisateur de soumettre à nouveau le document ; le rapport sera remplacé par une nouvelle tentative.

Où il apparaît dans les réponses d’API

Le rapport NFC est transmis dans le tableau nfc_verifications[] — toujours un tableau JSON, jamais un objet nfc unique. Plusieurs entrées apparaissent lorsqu’un workflow effectue l’étape NFC plus d’une fois (par exemple dans le cadre d’un flux de step-up) ; chaque entrée comporte son propre node_id.

API de décision de session — apparaît sous forme de nfc_verifications[] au niveau racine de GET /v3/session/{sessionId}/decision/. Voir Récupérer la décision de session.
Webhooks — les payloads status.updated incluent le même tableau nfc_verifications[] dès que l’étape NFC a produit des données. Voir Webhooks.
NFC autonome — pour la soumission directe de la puce, voir la Vue d’ensemble du NFC.

Lorsque votre workflow comprend une étape NFC qui a été ignorée ou contournée, le payload de décision contient également un champ de premier niveau nfc_skip_reason indiquant précisément pourquoi — le document n’a pas de puce, le certificat du pays de délivrance n’est pas disponible, l’appareil n’a pas de lecteur NFC, la vérification s’est déroulée sans SDK natif (aucun accès NFC depuis un navigateur), la clé d’accès à la puce n’a pas pu être dérivée de la MRZ, une My Number Card n’a pas pu être lue via JPKI, ou l’utilisateur a choisi d’ignorer l’étape. Il reste null pour les résultats hors de cette taxonomie — le plus souvent un utilisateur qui a abandonné en cours de tentative (statut du rapport Not Finished) ou une session où le NFC est toujours en attente. Voir les Motifs de non-exécution pour les valeurs exactes.

L’ancienne documentation faisait référence à un champ unique nfc. Ce format n’existe pas sur l’endpoint de décision v3 — il apparaît uniquement sur les destinations explicitement associées aux webhooks V2, où il contient également chip_protocol et jpki. Lisez toujours response.nfc_verifications[0] et itérez sur le tableau.

Schéma

Le schéma canonique champ par champ se trouve sur la page de référence Modèles de données. Les champs ci-dessous reflètent ce schéma canonique.

Champ	Type	Description
`status`	`"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"`	Statut de l’étape NFC (voir les significations ci-dessus).
`node_id`	string \| null	Nœud du graphe de workflow qui a généré ce rapport. Permet de distinguer deux vérifications NFC dans un workflow à plusieurs étapes.
`is_nfc_skipped`	boolean	`true` lorsque cette étape NFC a été explicitement ignorée au lieu d’être lue.
`skip_reason`	string \| null	Raison pour laquelle l’étape a été ignorée — défini uniquement lorsque `is_nfc_skipped` vaut `true`. Mêmes valeurs que `nfc_skip_reason` au niveau de la session ; voir Raisons d’omission.
`chip_protocol`	`"icao"` \| `"jpki"`	Mode de lecture de la puce. `icao` : puce de passeport électronique ou d’eID ICAO 9303. `jpki` : Japan My Number Card, dont le résultat se trouve sous `jpki` ; les champs ICAO ci-dessous (`portrait_image`, `signature_image`, `chip_data`, `authenticity`, `certificate_summary`) sont alors `null`. Également défini pour les étapes ignorées.
`jpki`	object \| null	Ce qu’a prouvé la lecture de la My Number Card ; voir Champs JPKI. `null` pour les puces ICAO, pour les étapes ignorées et lorsque l’étape s’est terminée sans lecture de carte.
`portrait_image`	string (signed URL) \| null	Portrait extrait de la puce (DG2). Lien présigné à courte durée de validité — téléchargez-le rapidement ; récupérez à nouveau la décision pour obtenir une nouvelle URL.
`signature_image`	string (signed URL) \| null	Image de la signature du titulaire issue de la puce (DG7), si présente. Même comportement : lien présigné à courte durée de validité.
`chip_data`	object \| null	Objet plat contenant les données biographiques analysées à partir de la puce. Toujours présent après une lecture réussie : `dgs` (liste des groupes de données lus), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (code de document MRZ, par ex. `P`), `document_number`, `optional_data`, les chiffres de contrôle de la MRZ (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string` et `mrz_type` (`TD1`/`TD2`/`TD3`). Lorsque la puce contient le DG11, `place_of_birth` et `address` sont ajoutés (ainsi que `full_name` / `full_name_non_latin` pour les documents comportant un nom non latin) ; ces clés sont absentes, et non nulles, dans le cas contraire. `null` lorsque l’étape NFC a été ignorée.
`authenticity`	object \| null	Résultats de l’authentification passive ICAO, ci-dessous. `null` pour une lecture JPKI.
`authenticity.sod_integrity`	boolean	`true` lorsque la signature SOD remonte jusqu’à une CSCA valide du pays de délivrance et que le DSC n’est ni révoqué ni expiré.
`authenticity.dg_integrity`	boolean	`true` lorsque le hachage de chaque groupe de données correspond à la valeur signée par le SOD. Une valeur `false` signifie que les données de la puce ont été altérées ou partiellement lues.
`certificate_summary`	object \| null	Résumé du DSC qui a signé cette puce : `issuer`, `subject`, `serial_number`, `not_valid_before`, `not_valid_after` (horodatages au format `YYYY-MM-DD HH:MM:SS`), ainsi qu’un objet `validation` contenant les résultats des vérifications individuelles (`csca_verified`, `csca_missing`, `dsc_revoked`, `dsc_expired`, `csca_expired`). `csca_missing` vaut `true` lorsque l’ancre de confiance CSCA émettrice du DSC n’est pas disponible. `null` lorsque le SOD n’a pas pu être chargé ou que l’étape a été ignorée.
`warnings[]`	array	Avertissements au niveau du module, chacun comportant `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description` et `node_id` — voir Avertissements NFC.

Valeurs de statut

Statut	Signification	Effet en aval
`Approved`	Puce lue et aucun avertissement déclenché avec une action Review ou Decline — y compris le cas où des avertissements ont été déclenchés mais dont l’action configurée est « No action ».	Compte comme une vérification NFC réussie ; ne fera pas passer, à elle seule, la session en cours d’examen.
`In Review`	Un avertissement s’est déclenché lorsque l’action configurée était Review (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME` ou l’un des avertissements `JPKI_*`, selon vos paramètres).	La session passe également à `In Review` jusqu’à ce qu’un réviseur intervienne.
`Declined`	Un avertissement s’est déclenché lorsque l’action configurée était Decline.	La session est refusée à moins qu’une autre branche approuvée ne valide le workflow.
`Not Finished`	L’utilisateur a abandonné l’étape NFC, l’appareil ne prenait pas en charge le NFC ou la lecture de la puce n’a jamais abouti.	La branche NFC n’a pas produit de résultat ; vérifiez les solutions de repli du workflow.
`Resub Requested`	Un réviseur a demandé une nouvelle soumission de cette étape.	Une nouvelle tentative remplace ce rapport dès que l’utilisateur réessaie.

Les deux avertissements relatifs aux certificats (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) sont à titre informatif : ils apparaissent dans warnings[] mais ne modifient jamais le status NFC à eux seuls. Voir Avertissements NFC pour la matrice complète des comportements.

Exemples

Approved — puce lue et cryptographiquement valide

{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": "https://<media-host>/.../epassport/<session-id>_signature.jpg?signature=...",
      "chip_data": {
        "dgs": ["DG1", "DG2", "DG7", "DG11"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000123",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "3",
        "optional_data_hash": "",
        "final_hash": "4",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04",
        "mrz_type": "TD3",
        "place_of_birth": "MADRID, MADRID",
        "address": "CALLE MAYOR 1, MADRID"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": []
    }
  ]
}

Declined — non-concordance OCR / puce

{
  "nfc_verifications": [
    {
      "status": "Declined",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": null,
      "chip_data": {
        "dgs": ["DG1", "DG2"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000254",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "6",
        "optional_data_hash": "",
        "final_hash": "6",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06",
        "mrz_type": "TD3"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "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"
        }
      ]
    }
  ]
}

Carte My Number japonaise (JPKI)

Une carte My Number japonaise est lue via JPKI dans les SDK natifs : la personne saisit le code PIN de la carte et la carte signe un défi à usage unique (voir comment cela fonctionne). Son rapport présente chip_protocol: "jpki" et transmet les preuves sous jpki. portrait_image, signature_image, chip_data, authenticity et certificate_summary sont null, car la carte ne contient aucune donnée ICAO.

La lecture de la carte My Number via JPKI n’est pas encore activée en production. D’ici là, une carte My Number ignore l’étape NFC avec le motif d’omission JPKI_UNAVAILABLE.

Champs JPKI

Champ	Type	Description
`jpki.certificate_types`	tableau de `"user_authentication"` \| `"signature"`	Les certificats de la carte ayant été lus. `user_authentication` (code PIN à 4 chiffres) est toujours lu ; `signature` (code PIN de signature) est lu lorsque le paramètre `jpki_request_attributes` du nœud NFC est activé, ce qui correspond à la valeur par défaut.
`jpki.chain_valid`	boolean	`true` lorsque chaque certificat remonte par chaîne de confiance à l’autorité de certification JPKI de son type, se situe dans sa période de validité et est un certificat de carte My Number de ce type.
`jpki.signature_valid`	boolean	`true` lorsque chaque signature générée par la carte sur le défi à usage unique est vérifiée avec succès. La carte ne signe qu’après la saisie de son code PIN, ce qui prouve que la personne détient la carte et connaît le code PIN.
`jpki.revocation_status`	`"good"` \| `"revoked"` \| `"unchecked"`	`good` : chaque certificat est confirmé comme non révoqué. `revoked` : un certificat est révoqué, par exemple parce que la carte a été déclarée perdue. `unchecked` : aucune réponse de révocation n’était disponible, de sorte qu’une carte révoquée ne peut pas être exclue ; n’est jamais traité comme `good`. La révocation n’est vérifiée qu’une fois la chaîne et la signature valides.
`jpki.ca_generation`	string \| null	Génération de l’autorité de certification JPKI ayant délivré les certificats, par exemple `"2023"`. `null` lorsqu’aucun certificat ne s’y rattache.
`jpki.certificate_expires_at`	string (ISO 8601) \| null	L’expiration la plus proche parmi les certificats lus.
`jpki.certificates[]`	array	Une entrée par certificat lu : `type`, `chain_valid`, `signature_valid`, `ca_generation`, `not_valid_before`, `not_valid_after` et `failure`. `failure` est `null` lorsque la chaîne est valide, sinon l’une des valeurs suivantes : `unreadable_certificate`, `untrusted_issuer`, `expired`, `not_yet_valid`, `wrong_policy` (n’est pas un certificat de carte My Number de ce type) ou `key_usage`.
`jpki.attributes`	object \| null	Données du titulaire issues du certificat de signature, une fois sa chaîne validée : `full_name` (tel qu’enregistré, généralement en système d’écriture japonais), `date_of_birth` (`YYYY-MM-DD`), `gender` (`M`, `F` ou `null`), `address`, et `name_substitute_characters` / `address_substitute_characters`, qui indiquent les caractères remplacés par un substitut car situés hors du jeu de caractères standard (`null` s’il n’y en a aucun). `null` lorsque le certificat de signature n’a pas été demandé ou que sa chaîne n’est pas valide.
`jpki.attributes_match_ocr`	boolean \| null	`true` lorsque les attributs correspondent aux données lues sur la photo de la même carte, `false` si l’un d’eux diffère (`JPKI_AND_OCR_DATA_NOT_SAME`), `null` quand rien n’a pu être comparé, y compris chaque fois que `attributes` est `null`.
`jpki.mismatched_attributes`	tableau de string	Les attributs qui diffèrent des données de la photo (`full_name`, `date_of_birth`, `gender`, `address`), jamais leurs valeurs.

Le rapport ne contient jamais les certificats eux-mêmes, leurs numéros de série, les signatures ou le numéro individuel (My Number) à 12 chiffres de la carte, que l’étape NFC ne lit jamais.

Exemple : lecture d’une carte My Number

{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": null,
      "signature_image": null,
      "chip_data": null,
      "is_nfc_skipped": false,
      "skip_reason": null,
      "chip_protocol": "jpki",
      "jpki": {
        "certificate_types": ["user_authentication", "signature"],
        "chain_valid": true,
        "signature_valid": true,
        "revocation_status": "good",
        "ca_generation": "2023",
        "certificate_expires_at": "2029-05-15T14:59:59Z",
        "certificates": [
          {
            "type": "user_authentication",
            "chain_valid": true,
            "signature_valid": true,
            "ca_generation": "2023",
            "not_valid_before": "2024-06-03T01:12:40+00:00",
            "not_valid_after": "2029-05-15T14:59:59+00:00",
            "failure": null
          },
          {
            "type": "signature",
            "chain_valid": true,
            "signature_valid": true,
            "ca_generation": "2023",
            "not_valid_before": "2024-06-03T01:12:40+00:00",
            "not_valid_after": "2029-05-15T14:59:59+00:00",
            "failure": null
          }
        ],
        "attributes": {
          "full_name": "山田 太郎",
          "date_of_birth": "1990-05-15",
          "gender": "M",
          "address": "東京都千代田区千代田1番1号",
          "name_substitute_characters": null,
          "address_substitute_characters": null
        },
        "attributes_match_ocr": true,
        "mismatched_attributes": []
      },
      "authenticity": null,
      "certificate_summary": null,
      "warnings": []
    }
  ]
}

Lorsque la vérification de révocation n’est pas disponible pour une lecture, le même rapport comporte revocation_status: "unchecked", un avertissement JPKI_REVOCATION_UNCHECKED et status: "In Review" avec les paramètres par défaut. Voir les avertissements NFC.

Note de sécurité

Les données de la puce NFC étant signées par l’autorité émettrice, un rapport approuvé avec sod_integrity: true et dg_integrity: true constitue la preuve d’identité la plus solide que Didit puisse produire. Considérez les URL des images signées (portrait_image, signature_image) comme temporaires : téléchargez-les rapidement et ne les mettez pas en cache publiquement — demandez à nouveau la décision lorsque vous avez besoin de liens actualisés.

Pages connexes

Avertissements NFC — liste complète des avertissements, causes et solutions.
Webhooks — écoutez l’événement status.updated pour recevoir le rapport NFC.
Modèles de données — Vérification NFC — schéma canonique avec l’ensemble des champs.
Documents pris en charge — les documents électroniques que Didit peut lire via NFC.

Authentification

Vérification

Surveillance

Plateforme

Rapport de vérification NFC : puce et authenticité

Vue d’ensemble

Où il apparaît dans les réponses d’API

Schéma

Valeurs de statut

Exemples

Approved — puce lue et cryptographiquement valide

Declined — non-concordance OCR / puce

Carte My Number japonaise (JPKI)

Champs JPKI

Exemple : lecture d’une carte My Number

Note de sécurité

Pages connexes

​Vue d’ensemble

​Où il apparaît dans les réponses d’API

​Schéma

​Valeurs de statut

​Exemples

​Approved — puce lue et cryptographiquement valide

​Declined — non-concordance OCR / puce

​Carte My Number japonaise (JPKI)

​Champs JPKI

​Exemple : lecture d’une carte My Number

​Note de sécurité

​Pages connexes

Vue d’ensemble

Où il apparaît dans les réponses d’API

Schéma

Valeurs de statut

Exemples

Approved — puce lue et cryptographiquement valide

Declined — non-concordance OCR / puce

Carte My Number japonaise (JPKI)

Champs JPKI

Exemple : lecture d’une carte My Number

Note de sécurité

Pages connexes