Langsung ke konten utama

Gambaran Umum

Peringatan pada laporan NFC menandai setiap kondisi yang diamati Didit saat membaca dan memvalidasi chip. Peringatan ini masuk ke dalam array warnings[] pada setiap item nfc_verifications[] (lihat laporan NFC), dengan feature yang diatur ke "NFC". Setiap entri mengikuti struktur objek peringatan umum: feature, risk, additional_data, log_type, short_description, long_description, node_id. Setiap peringatan memiliki tiga lapisan:
  1. Kode risk — pengidentifikasi stabil yang dapat Anda cocokkan di kode Anda (kode-kode yang tercantum di bawah ini).
  2. log_type — salah satu dari information, warning, atau error. Nilai ini ditentukan oleh tindakan yang dikonfigurasi untuk risiko tersebut di alur kerja Anda: Tidak ada tindakan → information, Peninjauan → warning, Tolak → error.
  3. Dampak keputusan — tindakan terkonfigurasi yang sama juga menentukan status laporan NFC: tindakan Peninjauan mengubah statusnya menjadi In Review, sedangkan tindakan Tolak mengubahnya menjadi Declined.
Empat risiko NFC dapat dikonfigurasi dengan cara ini (SKIPPED_NFC_VALIDATION, NFC_CHIP_NOT_VERIFIED, NFC_TRUST_ANCHOR_MISSING, NFC_AND_OCR_DATA_NOT_SAME), ditambah lima risiko Japan My Number Card, masing-masing dengan pengaturannya sendiri. Dua risiko sertifikat (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) bersifat informasional saja: keduanya selalu membawa log_type: "information" dan tidak pernah mengubah status NFC dengan sendirinya. Rangkaian lengkap kode risiko yang dihasilkan modul NFC tercantum di bawah ini. Tidak ada kode risiko NFC lainnya.

Peringatan yang dihasilkan

SKIPPED_NFC_VALIDATION bersifat saling eksklusif dengan NFC_CHIP_NOT_VERIFIED dan NFC_TRUST_ANCHOR_MISSING: peringatan verifikasi chip hanya dievaluasi ketika pembacaan chip tidak dilewati. Kedua peringatan verifikasi chip tersebut juga bersifat saling eksklusif.

String deskripsi yang persis

API mengembalikan string short_description dan long_description persis berikut untuk setiap risiko:

Alasan pelewatan

Peringatan SKIPPED_NFC_VALIDATION memuat additional_data.skip_reason, salah satu dari tujuh kode stabil yang menyatakan secara tepat alasan NFC tidak dijalankan (pada sesi yang direkam sebelum alasan pelewatan tersedia, additional_data mungkin bernilai null — perlakukan kolom ini sebagai opsional saat memproses keputusan historis). Taksonomi yang sama muncul pada tingkat sesi sebagai nfc_skip_reason pada payload keputusan — termasuk untuk sesi di mana NFC sama sekali tidak dapat dijalankan (dokumen tanpa chip, integrasi web) sehingga tidak ada laporan atau peringatan NFC yang dibuat.
Laporan NFC dan peringatan SKIPPED_NFC_VALIDATION hanya ada jika klien mencapai langkah NFC dan secara eksplisit melewatinya (biasanya USER_SKIPPED, atau DEVICE_WITHOUT_NFC saat pembaca ternyata tidak tersedia pada waktu pemindaian). Ketika langkah NFC dilewati sebelum sempat ditawarkan — dokumen tanpa chip, sertifikat tidak tersedia, kapabilitas NFC tidak dilaporkan, kunci MRZ tidak terbaca, JPKI tidak tersedia — tidak ada laporan atau peringatan yang dibuat dan alasannya hanya muncul di kolom nfc_skip_reason tingkat sesi, tanpa memengaruhi status sesi.

Konfigurasi

Tiga pengaturan alur kerja mengontrol cara peringatan NFC ditangani. Masing-masing dapat diatur ke Tidak ada tindakan, Tinjauan, atau Tolak:
  1. Tindakan lewati NFC (skip_nfc_action) — berlaku untuk SKIPPED_NFC_VALIDATION. Opsi lewati hanya ditawarkan kepada pengguna jika allow_nfc_skip diaktifkan.
  2. Tindakan chip tidak terverifikasi (unverified_chip_action) — berlaku untuk NFC_CHIP_NOT_VERIFIED dan NFC_TRUST_ANCHOR_MISSING, sehingga perilaku status sesi tetap sama sementara kode risiko menjelaskan alasan verifikasi gagal.
  3. Tindakan inkonsistensi data (inconsistent_data_action) — berlaku untuk NFC_AND_OCR_DATA_NOT_SAME. Ini adalah pengaturan inkonsistensi data yang sama dengan yang digunakan oleh Verifikasi Identitas.
Kedua risiko DSC_CERTIFICATE_* tidak memiliki pengaturan tindakan — keduanya selalu bersifat informatif. Risiko Japan My Number Card memiliki lima pengaturan tambahan, yang tercantum di bagian berikutnya.

Japan My Number Card (JPKI)

Japan My Number Card dibaca melalui JPKI, bukan ICAO 9303 (chip_protocol: "jpki"), sehingga risiko ICAO di atas tidak pernah dipicu untuk kartu ini. Pembacaan kartu ini memicu lima risiko berikut, masing-masing dengan pengaturannya sendiri pada node NFC: Pembacaan My Number Card yang dilewati akan memicu SKIPPED_NFC_VALIDATION dan mengikuti skip_nfc_action, seperti chip lainnya. Lihat Japan My Number Card (JPKI) untuk informasi tentang cara kerja pembacaannya.
Pembacaan My Number Card melalui JPKI belum diaktifkan di produksi. Hingga fitur ini aktif, My Number Card akan melewati langkah NFC dengan alasan lewati JPKI_UNAVAILABLE dan tidak satu pun risiko ini dipicu.

Contoh

Dalam peninjauan — chip tidak dapat diverifikasi

Di sini tindakan chip yang belum diverifikasi diatur ke Review, sehingga NFC_CHIP_NOT_VERIFIED membawa log_type: "warning" dan status laporan NFC adalah In Review. Entri DSC yang kedaluwarsa murni bersifat informasi.

Ditolak — ketidakcocokan chip / OCR

Di sini tindakan untuk ketidakkonsistenan data diatur ke Decline, sehingga peringatan membawa log_type: "error" dan status laporan NFC adalah Declined. Perhatikan bahwa ocr_mrz adalah array dari baris-baris MRZ sedangkan nfc_mrz adalah string MRZ tunggal yang digabungkan dari chip.

Dalam peninjauan: My Number Card tanpa jawaban pencabutan

Di sini jpki_revocation_unchecked_action mempertahankan nilai default-nya, Review, sehingga peringatan membawa log_type: "warning" dan status laporan NFC adalah In Review. Kartu itu sendiri terbukti sah: jpki.chain_valid dan jpki.signature_valid keduanya bernilai true.

Jenis peringatan

Setiap risiko diberi tingkat keparahan berdasarkan konfigurasi aplikasi Anda. Ketiga tingkat keparahan tersebut adalah:

Terkait

Terakhir diubah pada 7 November 2026