> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Отчёт по NFC-верификации: данные чипа и подлинность > Отчёт Didit по NFC и ePassport: расшифровка статуса, данных чипа, подлинности сертификатов, ответов API и примеры payload. ## Обзор **Отчёт об 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)](#японская-карта-my-number-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/`. См. [Получение решения по сессии](https://docs.didit.me/ru/sessions-api/retrieve-session.md). * **Webhooks** — payload события `status.updated` содержит тот же массив `nfc_verifications[]`, как только шаг NFC сформирует данные. См. [Вебхуки](https://docs.didit.me/ru/integration/webhooks.md). * **Автономный NFC** — для прямой отправки данных чипа см. [Обзор NFC](https://docs.didit.me/ru/core-technology/nfc-verification/overview.md). Если ваш сценарий включает шаг NFC, который был пропущен или обойдён, payload решения также содержит поле верхнего уровня `nfc_skip_reason`, указывающее точную причину — у документа нет чипа, сертификат страны выдачи недоступен, у устройства нет NFC-считывателя, верификация выполнялась без нативного SDK (нет доступа к NFC из браузера), ключ доступа к чипу не удалось вычислить на основе MRZ, карту My Number не удалось считать через JPKI или пользователь решил пропустить этот шаг. Оно остаётся со значением `null` для исходов вне этой классификации — чаще всего это пользователь, прервавший процесс посреди попытки (статус отчёта `Not Finished`), или сессия, где шаг NFC всё ещё ожидает выполнения. См. [Причины пропуска](https://docs.didit.me/ru/core-technology/nfc-verification/warnings-nfc-verification.md#причины-пропуска) для получения точных значений. > [!NOTE] > > В более ранней документации упоминалось отдельное поле `nfc`. Такой структуры **нет** на endpoint решения v3 — она появляется только для адресов назначения, явно привязанных к webhook V2, где также передаются `chip_protocol` и `jpki`. Всегда считывайте `response.nfc_verifications[0]` и выполняйте итерацию по массиву. ## Схема Каноническая схема с описанием каждого поля находится на справочной странице [Модели данных](https://docs.didit.me/ru/reference/data-models.md#nfc-верификация). Поля ниже полностью соответствуют этой канонической схеме. | Поле | Тип | Описание | | - | - | - | | `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` на уровне сессии; см. [Причины пропуска](https://docs.didit.me/ru/core-technology/nfc-verification/warnings-nfc-verification.md#причины-пропуска). | | `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](#поля-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-предупреждения](https://docs.didit.me/ru/core-technology/nfc-verification/warnings-nfc-verification.md). | ## Значения статуса | Статус | Значение | Влияние на последующие этапы | | - | - | - | | `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` | Проверяющий запросил повторное прохождение этого шага. | Как только пользователь сделает повторную попытку, новый результат заменит этот отчёт. | > [!NOTE] > > Два предупреждения по сертификатам (`DSC_CERTIFICATE_REVOKED`, `DSC_CERTIFICATE_EXPIRED`) являются информационными: они появляются в `warnings[]`, но сами по себе никогда не меняют `status` NFC. Полную матрицу поведения см. в разделе [NFC-предупреждения](https://docs.didit.me/ru/core-technology/nfc-verification/warnings-nfc-verification.md). ## Примеры ### Одобрено — чип прочитан и криптографически валиден ```json theme={null} { "nfc_verifications": [ { "status": "Approved", "node_id": "nfc_primary", "portrait_image": "https:///.../epassport/_face.jpg?signature=...", "signature_image": "https:///.../epassport/_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/.../epassport/_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 [!WARNING] > > Считывание карт 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 ```json theme={null} { "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](https://docs.didit.me/ru/core-technology/nfc-verification/warnings-nfc-verification.md#японская-карта-my-number-card-jpki). ## Примечание о безопасности Данные чипа NFC подписаны органом выдачи, поэтому отчёт со статусом «Одобрен» с `sod_integrity: true` и `dg_integrity: true` представляет собой самое сильное возможное подтверждение личности, которое может предоставить Didit. Относитесь к подписанным URL-адресам изображений (`portrait_image`, `signature_image`) как к кратковременным: своевременно скачивайте их и не кэшируйте публично — запросите решение повторно, если вам потребуются свежие ссылки. ## Связанные разделы * [Предупреждения NFC](https://docs.didit.me/ru/core-technology/nfc-verification/warnings-nfc-verification.md) — полный список значений перечисления предупреждений, причины и способы устранения. * [webhook](https://docs.didit.me/ru/integration/webhooks.md) — подпишитесь на событие `status.updated`, чтобы получать отчёт NFC. * [Модели данных — NFC-верификация](https://docs.didit.me/ru/reference/data-models.md#nfc-верификация) — каноническая схема со всеми полями. * [Поддерживаемые документы](https://docs.didit.me/ru/core-technology/nfc-verification/supported-documents-nfc-verification.md) — какие электронные документы Didit может считывать через NFC. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.