Informe de verificació NFC: dades del xip i autenticitat

Visió general

L’informe de verificació NFC recull el que Didit ha llegit i validat del xip NFC d’un document: un passaport electrònic, un document d’identitat electrònic o un altre document electrònic segons la norma ICAO 9303. Inclou les dades biogràfiques del xip, comprovacions d’integritat criptogràfica (SOD i resums dels Data Groups) i un resum del Document Signer Certificate (DSC) utilitzat pel país emissor. L’informe es genera després que l’usuari completi el pas d’NFC en un flux de treball. Didit llegeix els Data Groups del xip al dispositiu de l’usuari, verifica la signatura del Document Security Object (SOD) amb el certificat CSCA del país emissor, comprova cada resum de Data Group amb els valors signats pel SOD i compara l’MRZ del xip amb l’MRZ extret per OCR de la part visible del document. La targeta My Number del Japó es llegeix mitjançant JPKI (chip_protocol: "jpki"): el seu informe inclou les comprovacions de certificat, signatura, revocació i dades del titular sota jpki, i els camps d’ICAO es mantenen com a null. Consulta Japan My Number Card (JPKI). Cada informe inclou el seu propi status —independent de l’estat global de la sessió— que reflecteix com s’ha resolt el pas d’NFC de manera aïllada:

Aprovat — el xip s’ha llegit i cap de les advertències que s’han generat està configurada per dirigir el pas a revisió o rebutjar-lo.
En Revisió — s’ha activat com a mínim una advertència que té configurada l’acció Revisió (per exemple, NFC_CHIP_NOT_VERIFIED o NFC_TRUST_ANCHOR_MISSING quan l’acció per a xip no verificat està configurada com a Revisió, o JPKI_REVOCATION_UNCHECKED amb la seva acció per defecte).
Rebutjat — s’ha activat com a mínim una advertència que té configurada l’acció Rebutjar (per exemple, NFC_AND_OCR_DATA_NOT_SAME quan l’acció d’inconsistència de dades està configurada com a Rebutjar).
No finalitzat — l’usuari no ha completat mai el pas d’NFC; la lectura del xip s’ha abandonat o el dispositiu no era compatible amb NFC.
Nova tramesa sol·licitada — un revisor ha demanat a l’usuari que torni a enviar la informació; l’informe se substituirà per un nou intent.

On apareix a les respostes de l’API

L’informe d’NFC s’inclou dins de l’array nfc_verifications[] —sempre un array JSON, mai un objecte nfc singular. Apareixen diverses entrades quan un flux de treball executa NFC més d’una vegada (per exemple, en un flux step-up); cada entrada inclou el seu propi node_id.

API de decisió de la sessió — apareix com a nfc_verifications[] al nivell superior de GET /v3/session/{sessionId}/decision/. Consulta Obtenir la decisió de la sessió.
Webhooks — els payloads de status.updated inclouen el mateix array nfc_verifications[] un cop el pas d’NFC ha generat dades. Consulta Webhooks.
NFC independent — per a l’enviament directe del xip, consulta la Visió general d’NFC.

Quan el teu flux de treball inclou un pas d’NFC que s’ha omès o evitat, el payload de decisió també inclou un camp de nivell superior nfc_skip_reason que indica exactament el motiu: el document no té xip, el certificat del país emissor no està disponible, el dispositiu no disposa de lector NFC, la verificació s’ha executat sense un SDK natiu (sense accés a NFC des d’un navegador), la clau d’accés al xip no s’ha pogut derivar de l’MRZ, una targeta My Number no s’ha pogut llegir mitjançant JPKI o l’usuari ha decidit ometre el pas. Es manté com a null per a resultats fora d’aquesta taxonomia; el cas més habitual és un usuari que ha abandonat a mig intent (estat de l’informe Not Finished) o una sessió on l’NFC encara està pendent. Consulta Motius d’omissió per conèixer els valors exactes.

La documentació anterior feia referència a un camp singular nfc. Aquesta estructura no existeix a l’endpoint de decisió v3: només apareix en destinacions fixades explícitament als webhooks V2, on també inclou chip_protocol i jpki. Llegeix sempre response.nfc_verifications[0] i itera sobre l’array.

Esquema

L’esquema canònic camp per camp es troba a la pàgina de referència Models de dades. Els camps següents reflecteixen aquest esquema canònic.

Camp	Tipus	Descripció
`status`	`"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"`	Estat del pas d’NFC (consulta els significats anteriors).
`node_id`	string \| null	Node del graf de flux de treball que ha generat aquest informe. Et permet distingir dues comprovacions d’NFC en un flux de treball de diversos passos.
`is_nfc_skipped`	boolean	`true` quan aquest pas d’NFC s’ha omès explícitament en lloc de llegir el xip.
`skip_reason`	string \| null	Per què s’ha omès el pas: només s’estableix quan `is_nfc_skipped` és `true`. Té els mateixos valors que `nfc_skip_reason` a nivell de sessió; consulta Motius d’omissió.
`chip_protocol`	`"icao"` \| `"jpki"`	Com es llegeix el xip. `icao`: un xip de passaport electrònic o document d’identitat electrònic ICAO 9303. `jpki`: una targeta My Number del Japó, el resultat de la qual s’inclou a `jpki`; els camps ICAO inferiors (`portrait_image`, `signature_image`, `chip_data`, `authenticity`, `certificate_summary`) són llavors `null`. També s’estableix en passos omesos.
`jpki`	object \| null	El que ha demostrat la lectura d’una targeta My Number; consulta Camps de JPKI. `null` per a xips ICAO, per a passos omesos i quan el pas s’ha tancat sense llegir cap targeta.
`portrait_image`	string (URL signat) \| null	Retrat extret del xip (DG2). Enllaç presignat de curta durada: descarrega’l immediatament; torna a consultar la decisió per obtenir un URL actualitzat.
`signature_image`	string (URL signat) \| null	Imatge de la signatura del titular extreta del xip (DG7), quan està present. Té el mateix comportament que un enllaç presignat de curta durada.
`chip_data`	object \| null	Objecte pla amb les dades biogràfiques analitzades del xip. Sempre present després d’una lectura satisfactòria: `dgs` (llista de grups de dades llegits), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (codi de document MRZ, p. ex. `P`), `document_number`, `optional_data`, els dígits de control del MRZ (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string` i `mrz_type` (`TD1`/`TD2`/`TD3`). Quan el xip conté el DG11, s’afegeixen `place_of_birth` i `address` (i `full_name` / `full_name_non_latin` per a documents amb un nom no llatí); en cas contrari, aquestes claus són absents, no pas null. `null` quan el pas d’NFC s’ha omès.
`authenticity`	object \| null	Resultats de l’autenticació passiva ICAO, detallats a continuació. `null` per a una lectura JPKI.
`authenticity.sod_integrity`	boolean	`true` quan la signatura del SOD s’encadena amb una CSCA vàlida del país emissor i el DSC no està ni revocat ni caducat.
`authenticity.dg_integrity`	boolean	`true` quan el hash de cada grup de dades coincideix amb el valor que va signar el SOD. Un valor `false` significa que les dades del xip s’han manipulat o s’han llegit parcialment.
`certificate_summary`	object \| null	Resum del DSC que ha signat aquest xip: `issuer`, `subject`, `serial_number`, `not_valid_before`, `not_valid_after` (marques de temps com a `YYYY-MM-DD HH:MM:SS`), a més d’un objecte `validation` amb els resultats de les comprovacions individuals (`csca_verified`, `csca_missing`, `dsc_revoked`, `dsc_expired`, `csca_expired`). `csca_missing` és `true` quan l’àncora de confiança CSCA emissora del DSC no està disponible. `null` quan el SOD no s’ha pogut carregar o el pas s’ha omès.
`warnings[]`	array	Advertències a nivell de mòdul, cadascuna amb `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description` i `node_id`; consulta Advertències d’NFC.

Valors d’estat

Estat	Significat	Efecte posterior
`Approved`	El xip s’ha llegit i no s’ha activat cap advertència amb una acció de revisió o rebuig, incloent-hi el cas en què s’han activat advertències però la seva acció configurada és “No action”.	Compta com una comprovació d’NFC satisfactòria; per si mateix, no enviarà la sessió a revisió.
`In Review`	S’ha activat una advertència l’acció configurada de la qual és de revisió (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME` o una de les advertències `JPKI_*`, segons la teva configuració).	La sessió també passa a `In Review` fins que un revisor prengui una decisió.
`Declined`	S’ha activat una advertència l’acció configurada de la qual és de rebuig.	La sessió es rebutja llevat que una altra branca aprovada compleixi el flux de treball.
`Not Finished`	L’usuari ha abandonat el pas d’NFC, el dispositiu no tenia compatibilitat amb NFC o la lectura del xip no s’ha completat mai.	La branca d’NFC no ha generat cap resultat; comprova les alternatives del flux de treball.
`Resub Requested`	Un revisor ha sol·licitat tornar a enviar aquest pas.	Un nou intent substitueix aquest informe quan l’usuari faci un nou intent.

Les dues advertències de certificat (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) són informatives: apareixen a warnings[], però per si soles mai canvien l’status d’NFC. Consulta Advertències d’NFC per veure la matriu completa de comportament.

Exemples

Approved: xip llegit i criptogràficament vàlid

{
  "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: discrepància entre OCR i xip

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

Japan My Number Card (JPKI)

Una Japan My Number Card es llegeix a través de JPKI en els SDK natius: la persona introdueix el PIN de la targeta i la targeta signa un repte d’un sol ús (consulta com funciona). El seu informe té chip_protocol: "jpki" i inclou les evidències a jpki. portrait_image, signature_image, chip_data, authenticity i certificate_summary són null, perquè la targeta no conté dades ICAO.

La lectura de la My Number Card a través de JPKI encara no està activada a producció. Fins que ho estigui, una My Number Card omet el pas NFC amb el motiu d’omissió JPKI_UNAVAILABLE.

Camps JPKI

Camp	Tipus	Descripció
`jpki.certificate_types`	array de `"user_authentication"` \| `"signature"`	Els certificats de la targeta llegits. `user_authentication` (PIN de 4 xifres) sempre es llegeix; `signature` (PIN de signatura) es llegeix quan la configuració `jpki_request_attributes` del node NFC està activada, que és el valor per defecte.
`jpki.chain_valid`	boolean	`true` quan tots els certificats formen una cadena amb l’autoritat de certificació JPKI del seu tipus, estan dins del seu període de validesa i són certificats de My Number Card d’aquest tipus.
`jpki.signature_valid`	boolean	`true` quan totes les signatures que la targeta ha generat sobre el repte d’un sol ús són vàlides. La targeta només signa un cop s’ha introduït el seu PIN, de manera que això demostra que la persona té la targeta i coneix el PIN.
`jpki.revocation_status`	`"good"` \| `"revoked"` \| `"unchecked"`	`good`: es confirma que cap certificat està revocat. `revoked`: un certificat està revocat, per exemple perquè la targeta s’ha denunciat com a perduda. `unchecked`: no hi havia cap resposta de revocació disponible, de manera que no es pot descartar una targeta revocada; mai es tracta com a `good`. La revocació només es comprova un cop la cadena i la signatura són vàlides.
`jpki.ca_generation`	string \| null	Generació de l’autoritat de certificació JPKI que ha emès els certificats, per exemple `"2023"`. `null` quan cap certificat no hi encadena.
`jpki.certificate_expires_at`	string (ISO 8601) \| null	La caducitat més propera entre els certificats llegits.
`jpki.certificates[]`	array	Una entrada per certificat llegit: `type`, `chain_valid`, `signature_valid`, `ca_generation`, `not_valid_before`, `not_valid_after` i `failure`. `failure` és `null` quan la cadena és vàlida, altrament un de `unreadable_certificate`, `untrusted_issuer`, `expired`, `not_yet_valid`, `wrong_policy` (no és un certificat de My Number Card d’aquest tipus) o `key_usage`.
`jpki.attributes`	object \| null	Les dades del titular extretes del certificat de signatura, un cop la seva cadena és vàlida: `full_name` (tal com està registrat, normalment en el sistema d’escriptura japonès), `date_of_birth` (`YYYY-MM-DD`), `gender` (`M`, `F` o `null`), `address` i `name_substitute_characters` / `address_substitute_characters`, que indiquen caràcters substituïts per un substitut perquè queden fora del conjunt de caràcters estàndard (`null` quan no n’hi ha cap). `null` quan no s’ha sol·licitat el certificat de signatura o la seva cadena no és vàlida.
`jpki.attributes_match_ocr`	boolean \| null	`true` quan els atributs coincideixen amb les dades llegides de la fotografia de la mateixa targeta, `false` quan algun d’ells difereix (`JPKI_AND_OCR_DATA_NOT_SAME`), `null` quan no s’ha pogut comparar res, també quan `attributes` sigui `null`.
`jpki.mismatched_attributes`	array de string	Els atributs que difereixen de les dades de la foto (`full_name`, `date_of_birth`, `gender`, `address`), mai els seus valors.

L’informe mai conté els certificats en si, els seus números de sèrie, les signatures o el Número Individual (My Number) de 12 xifres de la targeta, que el pas NFC mai llegeix.

Exemple: lectura de My Number Card

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

Quan la comprovació de revocació no està disponible per a una lectura, el mateix informe té revocation_status: "unchecked", una advertència JPKI_REVOCATION_UNCHECKED i status: "In Review" amb la configuració per defecte. Consulta les advertències d’NFC.

Nota de seguretat

Les dades del xip NFC estan signades per l’autoritat emissora, de manera que un informe aprovat amb sod_integrity: true i dg_integrity: true és la prova d’identitat més sòlida possible que Didit pot generar. Tracta els URL d’imatge signats (portrait_image, signature_image) com a recursos de curta durada: descarrega’ls ràpidament i no els emmagatzemis en memòria cau pública; torna a sol·licitar la decisió quan necessitis enllaços actualitzats.

Relacionat

Advertències d’NFC — enumeració completa d’advertències, causes i resolució.
Webhooks — escolta l’esdeveniment status.updated per rebre l’informe d’NFC.
Models de dades — Verificació NFC — esquema canònic amb tots els camps.
Documents admesos — quins documents electrònics pot llegir Didit mitjançant NFC.

Autenticació

Verificació

Monitoratge

Plataforma

Informe de verificació NFC: dades del xip i autenticitat

Visió general

On apareix a les respostes de l’API

Esquema

Valors d’estat

Exemples

Approved: xip llegit i criptogràficament vàlid

Declined: discrepància entre OCR i xip

Japan My Number Card (JPKI)

Camps JPKI

Exemple: lectura de My Number Card

Nota de seguretat

Relacionat

​Visió general

​On apareix a les respostes de l’API

​Esquema

​Valors d’estat

​Exemples

​Approved: xip llegit i criptogràficament vàlid

​Declined: discrepància entre OCR i xip

​Japan My Number Card (JPKI)

​Camps JPKI

​Exemple: lectura de My Number Card

​Nota de seguretat

​Relacionat

Visió general

On apareix a les respostes de l’API

Esquema

Valors d’estat

Exemples

Approved: xip llegit i criptogràficament vàlid

Declined: discrepància entre OCR i xip

Japan My Number Card (JPKI)

Camps JPKI

Exemple: lectura de My Number Card

Nota de seguretat

Relacionat