Отчёт по NFC-верификации: данные чипа и подлинность

Обзор

Отчёт об NFC-верификации фиксирует данные, которые Didit считал и проверил с NFC-чипа документа — электронного паспорта (ePassport), электронного удостоверения личности (eID) или другого электронного документа стандарта ICAO 9303. Он включает биографические данные с чипа, криптографические проверки целостности (хэши SOD и Data Groups), а также сводные сведения о сертификате подписанта документа (DSC), использованном страной выдачи. Отчёт формируется после того, как пользователь завершает шаг NFC в сценарии. Didit считывает Data Groups чипа на устройстве пользователя, проверяет подпись объекта безопасности документа (Document Security Object, SOD) по CSCA-сертификату страны выдачи, сверяет хэш каждой Data Group со значениями, подписанными в SOD, и сопоставляет MRZ с чипа с MRZ, распознанной с помощью OCR с видимой стороны документа. Японская карта My Number считывается через JPKI (chip_protocol: "jpki"): её отчёт содержит проверки сертификата, подписи, статуса отзыва и данных владельца в объекте jpki, а поля ICAO остаются со значением null. См. Japan My Number Card (JPKI). Каждый отчёт имеет собственный статус status — независимо от общего статуса сессии — отражающий результат выполнения только шага NFC:

Одобрено — чип был считан, и ни одно из сработавших предупреждений не настроено так, чтобы направить шаг на проверку или отклонить его.
На проверке — сработало как минимум одно предупреждение, для которого настроено действие Проверка (например, NFC_CHIP_NOT_VERIFIED или NFC_TRUST_ANCHOR_MISSING, когда действие для непроверенного чипа настроено как «Проверка», либо JPKI_REVOCATION_UNCHECKED со стандартным действием).
Отклонено — сработало как минимум одно предупреждение, для которого настроено действие Отклонить (например, NFC_AND_OCR_DATA_NOT_SAME, когда действие для несоответствия данных настроено как «Отклонить»).
Не завершено — пользователь не завершил шаг NFC; считывание чипа было прервано либо устройство не поддерживает NFC.
Запрошена повторная отправка — проверяющий запросил повторную отправку у пользователя; отчёт будет заменён отчётом о новой попытке.

Где отчёт появляется в ответах API

Отчёт NFC передаётся внутри массива nfc_verifications[] — всегда в виде JSON-массива, а не единичного объекта nfc. Несколько записей появляются, когда сценарий выполняет NFC более одного раза (например, в сценарии усиленной проверки); каждая запись содержит собственный node_id.

API решения по сессии — передаётся как nfc_verifications[] на верхнем уровне ответа GET /v3/session/{sessionId}/decision/. См. Получение решения по сессии.
Webhooks — payload события status.updated содержит тот же массив nfc_verifications[], как только шаг NFC сформирует данные. См. Вебхуки.
Автономный NFC — для прямой отправки данных чипа см. Обзор NFC.

Если ваш сценарий включает шаг NFC, который был пропущен или обойдён, payload решения также содержит поле верхнего уровня nfc_skip_reason, указывающее точную причину — у документа нет чипа, сертификат страны выдачи недоступен, у устройства нет NFC-считывателя, верификация выполнялась без нативного SDK (нет доступа к NFC из браузера), ключ доступа к чипу не удалось вычислить на основе MRZ, карту My Number не удалось считать через JPKI или пользователь решил пропустить этот шаг. Оно остаётся со значением null для исходов вне этой классификации — чаще всего это пользователь, прервавший процесс посреди попытки (статус отчёта Not Finished), или сессия, где шаг NFC всё ещё ожидает выполнения. См. Причины пропуска для получения точных значений.

В более ранней документации упоминалось отдельное поле nfc. Такой структуры нет на endpoint решения v3 — она появляется только для адресов назначения, явно привязанных к webhook V2, где также передаются chip_protocol и jpki. Всегда считывайте response.nfc_verifications[0] и выполняйте итерацию по массиву.

Схема

Каноническая схема с описанием каждого поля находится на справочной странице Модели данных. Поля ниже полностью соответствуют этой канонической схеме.

Поле	Тип	Описание
`status`	`"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"`	Статус NFC-шага (значения см. выше).
`node_id`	string \| null	Узел графа сценария, сформировавший этот отчёт. Позволяет различать две NFC-проверки в многошаговом сценарии.
`is_nfc_skipped`	boolean	`true`, если этот NFC-шаг был явно пропущен, а не прочитан.
`skip_reason`	string \| null	Причина пропуска шага — задаётся только тогда, когда `is_nfc_skipped` равен `true`. Те же значения, что и у `nfc_skip_reason` на уровне сессии; см. Причины пропуска.
`chip_protocol`	`"icao"` \| `"jpki"`	Способ чтения чипа. `icao`: чип электронного паспорта (ePassport) или удостоверения личности (eID) по стандарту ICAO 9303. `jpki`: японская карта My Number Card, результат чтения которой находится в объекте `jpki`; в этом случае поля ICAO ниже (`portrait_image`, `signature_image`, `chip_data`, `authenticity`, `certificate_summary`) содержат `null`. Также задаётся для пропущенных шагов.
`jpki`	object \| null	Данные, подтверждённые при чтении карты My Number Card; см. Поля JPKI. `null` для чипов ICAO, для пропущенных шагов и в случаях, когда шаг завершился без чтения карты.
`portrait_image`	string (подписанный URL) \| null	Фотопортрет, извлечённый из чипа (DG2). Краткосрочная предварительно подписанная ссылка — скачивайте оперативно; повторно запросите решение, чтобы получить актуальный URL.
`signature_image`	string (подписанный URL) \| null	Изображение подписи владельца из чипа (DG7), если присутствует. Ссылка имеет такие же краткосрочные свойства предварительно подписанной ссылки.
`chip_data`	object \| null	Плоский объект с биографическими данными, распарсенными из чипа. Всегда присутствует после успешного чтения: `dgs` (список прочитанных групп данных), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (код документа в MRZ, например `P`), `document_number`, `optional_data`, контрольные цифры MRZ (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string` и `mrz_type` (`TD1`/`TD2`/`TD3`). Если чип содержит DG11, добавляются `place_of_birth` и `address` (а также `full_name` / `full_name_non_latin` для документов с нелатинским именем); в противном случае эти ключи отсутствуют, а не содержат null. `null`, если NFC-шаг был пропущен.
`authenticity`	object \| null	Результаты пассивной аутентификации ICAO, приведены ниже. `null` для чтения JPKI.
`authenticity.sod_integrity`	boolean	`true`, если подпись SOD образует цепочку доверия к действующему CSCA страны выдачи, а DSC не отозван и срок его действия не истёк.
`authenticity.dg_integrity`	boolean	`true`, если хэш каждой группы данных (Data Group) совпадает со значением, подписанным в SOD. Значение `false` означает, что данные чипа были скомпрометированы или прочитаны не полностью.
`certificate_summary`	object \| null	Сводные данные DSC, подписавшего этот чип: `issuer`, `subject`, `serial_number`, `not_valid_before`, `not_valid_after` (временные метки в формате `YYYY-MM-DD HH:MM:SS`), а также объект `validation` с результатами отдельных проверок (`csca_verified`, `csca_missing`, `dsc_revoked`, `dsc_expired`, `csca_expired`). `csca_missing` равен `true`, если якорный сертификат доверия CSCA страны выдачи DSC недоступен. `null`, если SOD не удалось загрузить или шаг был пропущен.
`warnings[]`	array	Предупреждения на уровне модуля, каждое с полями `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description` и `node_id` — см. NFC-предупреждения.

Значения статуса

Статус	Значение	Влияние на последующие этапы
`Approved`	Чип прочитан, и не сработало ни одно предупреждение с действием Review или Decline — включая случай, когда предупреждения сработали, но для них настроено действие «No action».	Считается успешной NFC-проверкой; само по себе не переводит сессию на проверку.
`In Review`	Сработало предупреждение, для которого настроено действие Review (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME` или одно из предупреждений `JPKI_*`, в зависимости от ваших настроек).	Сессия также переходит в статус `In Review` до тех пор, пока проверяющий не примет решение.
`Declined`	Сработало предупреждение, для которого настроено действие Decline.	Сессия отклонена, если только другая одобренная ветвь не удовлетворяет условиям сценария.
`Not Finished`	Пользователь прервал NFC-шаг, на устройстве отсутствовала поддержка NFC или чтение чипа не завершилось.	NFC-ветвь не сформировала результат; проверьте резервные ветви сценария.
`Resub Requested`	Проверяющий запросил повторное прохождение этого шага.	Как только пользователь сделает повторную попытку, новый результат заменит этот отчёт.

Два предупреждения по сертификатам (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) являются информационными: они появляются в warnings[], но сами по себе никогда не меняют status NFC. Полную матрицу поведения см. в разделе NFC-предупреждения.

Примеры

Одобрено — чип прочитан и криптографически валиден

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

Отклонено — несоответствие между OCR и чипом

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

Японская карта My Number (JPKI)

Японская карта My Number считывается через JPKI в нативных SDK: человек вводит PIN-код карты, и карта подписывает одноразовый челлендж (см. как это работает). Её отчёт содержит chip_protocol: "jpki" и включает подтверждающие данные в объекте jpki. Поля portrait_image, signature_image, chip_data, authenticity и certificate_summary имеют значение null, поскольку карта не содержит данных ICAO.

Считывание карт My Number через JPKI пока не включено в продакшене. До его включения карта My Number пропускает шаг NFC с причиной пропуска JPKI_UNAVAILABLE.

Поля JPKI

Поле	Тип	Описание
`jpki.certificate_types`	array of `"user_authentication"` \| `"signature"`	Считанные сертификаты карты. `user_authentication` (4-значный PIN-код) считывается всегда; `signature` (PIN-код подписи) считывается, если включена настройка узла NFC `jpki_request_attributes`, которая активна по умолчанию.
`jpki.chain_valid`	boolean	`true`, если каждый сертификат выстраивает цепочку доверия к центру сертификации JPKI соответствующего типа, находится в пределах срока действия и является сертификатом карты My Number этого типа.
`jpki.signature_valid`	boolean	`true`, если каждая подпись, сформированная картой для одноразового челленджа, проходит проверку. Карта ставит подпись только после ввода PIN-кода, что подтверждает владение картой и знание PIN-кода.
`jpki.revocation_status`	`"good"` \| `"revoked"` \| `"unchecked"`	`good`: подтверждено, что ни один сертификат не отозван. `revoked`: сертификат отозван, например, из-за заявления об утере карты. `unchecked`: ответ о статусе отзыва не был получен, поэтому нельзя исключать отзыв карты; никогда не расценивается как `good`. Проверка отзыва выполняется только после подтверждения валидности цепочки и подписи.
`jpki.ca_generation`	string \| null	Поколение центра сертификации JPKI, выпустившего сертификаты, например `"2023"`. `null`, если ни для одного сертификата не построена цепочка до такого центра.
`jpki.certificate_expires_at`	string (ISO 8601) \| null	Самая ранняя дата окончания срока действия среди считанных сертификатов.
`jpki.certificates[]`	array	По одной записи на каждый считанный сертификат: `type`, `chain_valid`, `signature_valid`, `ca_generation`, `not_valid_before`, `not_valid_after` и `failure`. `failure` имеет значение `null`, если цепочка валидна, иначе одно из значений: `unreadable_certificate`, `untrusted_issuer`, `expired`, `not_yet_valid`, `wrong_policy` (не сертификат карты My Number этого типа) или `key_usage`.
`jpki.attributes`	object \| null	Данные владельца из сертификата подписи после подтверждения валидности цепочки: `full_name` (как зарегистрировано, обычно в японской системе письма), `date_of_birth` (`YYYY-MM-DD`), `gender` (`M`, `F` или `null`), `address`, а также `name_substitute_characters` / `address_substitute_characters`, отмечающие символы, заменённые аналогами из-за отсутствия в стандартном наборе (`null`, если замен не было). `null`, если сертификат подписи не запрашивался или его цепочка недействительна.
`jpki.attributes_match_ocr`	boolean \| null	`true`, если атрибуты совпадают с данными, считанными с фотографии той же карты, `false`, если какой-либо из них отличается (`JPKI_AND_OCR_DATA_NOT_SAME`), `null`, если сравнение невозможно провести, включая случаи, когда `attributes` имеет значение `null`.
`jpki.mismatched_attributes`	array of string	Атрибуты, которые отличаются от данных с фотографии (`full_name`, `date_of_birth`, `gender`, `address`), но никогда их значения.

Отчёт никогда не содержит сами сертификаты, их серийные номера, подписи или 12-значный индивидуальный номер (My Number), который шаг NFC никогда не считывает.

Пример: считывание карты 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": []
    }
  ]
}

Если проверка отзыва недоступна при считывании, тот же отчёт имеет revocation_status: "unchecked", предупреждение JPKI_REVOCATION_UNCHECKED и status: "In Review" при настройках по умолчанию. См. предупреждения NFC.

Примечание о безопасности

Данные чипа NFC подписаны органом выдачи, поэтому отчёт со статусом «Одобрен» с sod_integrity: true и dg_integrity: true представляет собой самое сильное возможное подтверждение личности, которое может предоставить Didit. Относитесь к подписанным URL-адресам изображений (portrait_image, signature_image) как к кратковременным: своевременно скачивайте их и не кэшируйте публично — запросите решение повторно, если вам потребуются свежие ссылки.

Связанные разделы

Предупреждения NFC — полный список значений перечисления предупреждений, причины и способы устранения.
webhook — подпишитесь на событие status.updated, чтобы получать отчёт NFC.
Модели данных — NFC-верификация — каноническая схема со всеми полями.
Поддерживаемые документы — какие электронные документы Didit может считывать через NFC.

Аутентификация

Верификация

Мониторинг

Платформа

Отчёт по NFC-верификации: данные чипа и подлинность

Обзор

Где отчёт появляется в ответах API

Схема

Значения статуса

Примеры

Одобрено — чип прочитан и криптографически валиден

Отклонено — несоответствие между OCR и чипом

Японская карта My Number (JPKI)

Поля JPKI

Пример: считывание карты My Number

Примечание о безопасности

Связанные разделы

​Обзор

​Где отчёт появляется в ответах API

​Схема

​Значения статуса

​Примеры

​Одобрено — чип прочитан и криптографически валиден

​Отклонено — несоответствие между OCR и чипом

​Японская карта My Number (JPKI)

​Поля JPKI

​Пример: считывание карты My Number

​Примечание о безопасности

​Связанные разделы

Обзор

Где отчёт появляется в ответах API

Схема

Значения статуса

Примеры

Одобрено — чип прочитан и криптографически валиден

Отклонено — несоответствие между OCR и чипом

Японская карта My Number (JPKI)

Поля JPKI

Пример: считывание карты My Number

Примечание о безопасности

Связанные разделы