Peringatan & Kode Error Bukti Alamat

Gambaran Umum

Verifikasi Bukti Alamat (POA) memunculkan peringatan pada poa_verifications[].warnings[] untuk setiap masalah kualitas, keaslian, atau pencocokan yang terdeteksi selama ekstraksi dan analisis forensik. Setiap peringatan merupakan objek peringatan dengan feature yang diatur ke "PROOF_OF_ADDRESS". Sebagian kecil risiko selalu memaksakan status Declined; selebihnya mengikuti tindakan per risiko (DECLINE / REVIEW / NO_ACTION) yang dikonfigurasikan pada alur kerja Anda. Setiap risiko di bawah ini diverifikasi terhadap pipeline keputusan produksi; string deskripsi singkat dan panjang yang tepat direproduksi secara persis seperti aslinya di dalam tabel.

Ekstraksi POA memunculkan latensi 5–15 detik per dokumen. Peringatan hanya ditulis saat langkah alur kerja selesai; jangan lakukan polling lebih sering daripada setiap 5 detik.

Dua jalur produksi

Peringatan POA dihasilkan melalui dua jalur berbeda, dan rangkaian risikonya bervariasi di antara keduanya:

Sesi alur kerja (langkah POA di dalam sesi verifikasi) — endpoint pengunggahan pertama-tama menjalankan validasi pemblokiran dengan loop coba lagi (lihat Perilaku coba lagi), kemudian peringatan akhir yang disimpan dihitung oleh check_poa_risks ditambah pemeriksaan nama multidokumen.
API mandiri (POST /v3/poa/) — peringatan hanya berasal dari check_poa_risks. Tidak ada loop coba lagi, tidak ada konteks identitas terverifikasi, dan hanya satu dokumen, sehingga NAME_MISMATCH_ID_VERIFICATION, POA_NAME_MISMATCH_BETWEEN_DOCUMENTS, POA_MAX_ATTEMPTS_EXCEEDED, dan FUTURE_ISSUE_DATE tidak pernah dihasilkan oleh API mandiri. Kesalahan validasi pra-ekstraksi diabaikan pada jalur ini.

POOR_DOCUMENT_QUALITY didefinisikan dalam enum risiko dan dicadangkan dalam pemetaan tindakan, tetapi tidak ada jalur kode dalam pipeline POA yang menghasilkannya — risiko ini tidak pernah muncul di warnings[] pada kedua jalur. Jangan membuat percabangan logika berdasarkan risiko tersebut.

Peringatan penolakan otomatis (selalu memaksakan `Declined`)

Risiko-risiko ini berada dalam AUTO_DECLINE_RISKS; ketika dicatat, status POA adalah Declined terlepas dari konfigurasi, dan log_type selalu bernilai error.

Risiko	Penyebab	Remediasi yang disarankan
`MISSING_ADDRESS_INFORMATION`	Tidak ada alamat yang dapat diekstraksi dari dokumen.	Minta pengguna untuk mengirimkan ulang dokumen yang menunjukkan alamat mereka dengan jelas.
`POA_DOCUMENT_EXPIRED`	Dokumen dianggap kedaluwarsa karena salah satu dari dua kondisi: tanggal kedaluwarsa yang tercetak telah lewat, atau dokumen tersebut lebih lama dari usia maksimum yang dikonfigurasi untuk jenisnya. Default: 3 bulan untuk `UTILITY_BILL` dan `BANK_STATEMENT`, 12 bulan untuk `GOVERNMENT_ISSUED_DOCUMENT` dan `OTHER_POA_DOCUMENT` (satu bulan dihitung sebagai 30 hari; `-1` menonaktifkan pemeriksaan). `additional_data` selalu memuat `expiration_reason` (`printed_expiration` atau `age_window`), `document_type`, `document_subtype`, dan `issue_date`; jalur `printed_expiration` menambahkan `expiration_date`, dan jalur `age_window` menambahkan `max_age_months`.	Minta pengguna untuk memberikan dokumen yang valid atau lebih baru, atau naikkan `age_months` untuk jenis tersebut.
`INVALID_DOCUMENT_TYPE`	Dokumen tidak dapat diklasifikasikan ke dalam jenis POA yang didukung (`document_type` kembali ke `UNKNOWN`).	Minta pengguna untuk mengirimkan ulang; pastikan file tidak rusak.
`UNABLE_TO_VALIDATE_DOCUMENT_AGE`	Pemeriksaan usia dokumen itu sendiri gagal (terjadi kesalahan saat menghitung kedaluwarsa dari tanggal penerbitan).	Minta pengguna untuk memberikan dokumen dengan tanggal penerbitan yang dapat dibaca dengan jelas.

FUTURE_ISSUE_DATE juga terdaftar di AUTO_DECLINE_RISKS, tetapi hanya dihasilkan oleh satu sumber dalam validasi pra-ekstraksi (tanggal penerbitan lebih dari 7 hari di masa depan) yang kesalahannya hanya mengalir ke loop coba lagi alur kerja — ini muncul di sana sebagai kesalahan yang memblokir pengunggahan, tidak pernah dihasilkan oleh API mandiri, dan tidak ditulis ke warnings[]. Lihat Perilaku coba lagi.

Peringatan yang dapat dikonfigurasi

Setiap peringatan ini mengikuti salah satu opsi tindakan pada node POA alur kerja (DECLINE / REVIEW / NO_ACTION). log_type peringatan mengikuti tindakan yang dikonfigurasi: error untuk Tolak, warning untuk Tinjau, dan information untuk Tidak ada tindakan.

Risiko	Penyebab	Opsi tindakan	Bawaan
`NAME_MISMATCH_WITH_PROVIDED`	Skor nama pada dokumen berada di bawah `poa_name_match_score_threshold` (bawaan 86) jika dibandingkan dengan nama yang diberikan saat sesi dibuat (`expected_details`).	`poa_name_or_address_mismatch_action`	Tinjau
`NAME_MISMATCH_ID_VERIFICATION`	Nama pada dokumen memperoleh skor di bawah ambang batas dibandingkan dengan dokumen identitas yang telah diverifikasi. `additional_data`: `{ poa_name, kyc_name, match_score }`. Hanya untuk sesi alur kerja.	`poa_name_or_address_mismatch_action`	Tinjau
`ADDRESS_MISMATCH_WITH_PROVIDED`	Alamat yang diekstrak berbeda dari alamat yang diberikan melalui API, atau salah satu alamat tidak dapat diverifikasi sebagai alamat tempat tinggal.	`poa_name_or_address_mismatch_action`	Tinjau
`POA_COUNTRY_MISMATCH_WITH_PROVIDED`	Negara pada dokumen tidak sesuai dengan negara yang diberikan melalui API (dinormalisasi ke ISO-3). `additional_data`: `{ expected_country, extracted_country }`.	`poa_name_or_address_mismatch_action`	Tinjau
`POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`	Dua atau lebih dokumen POA dalam sesi yang sama memuat nama yang berbeda. `additional_data` mencakup kedua ID node, kedua nama, dan skor kecocokan. Hanya untuk sesi alur kerja.	`poa_name_or_address_mismatch_action`	Tinjau
`DOCUMENT_METADATA_MISMATCH`	Berkas kosong (`file_size` 0) atau format tanggal EXIF-nya tidak valid.	`poa_document_issues_action`	Tinjau
`SUSPECTED_DOCUMENT_MANIPULATION`	Forensik menemukan bukti manipulasi: dokumen dimodifikasi setelah ditandatangani secara digital (`is_tampered`), manipulasi teks overlay (dengan persegi panjang `additional_data.manipulated_regions`), editor PDF yang sudah dikenal, tanggal EXIF yang tidak konsisten, atau ekspor ulang yang mencurigakan. `additional_data.detection_method` menyebutkan pemeriksaan yang memicu peringatan.	`poa_document_authenticity_action`	Tolak
`POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`	Sebuah kolom teks dikosongkan lalu diketik ulang dengan font lain, dan berkas tidak memuat bukti apakah isinya berubah: editor daring juga mengetik ulang teks yang tidak diubah. Peringatan ini tidak pernah memicu `SUSPECTED_DOCUMENT_MANIPULATION` dengan sendirinya; jika sinyal lain memicunya pada dokumen yang sama, tindakan yang lebih ketat yang berlaku akan menentukan keputusan. `additional_data.detection_method` berisi `unproven_text_replacement`, dengan `replaced_text` dan `manipulated_regions`. Berkas yang tidak dapat diperiksa secara penuh juga memicu peringatan ini, karena bagian yang tidak diperiksa mungkin memuat kolom semacam itu: `detection_method` kemudian berisi `analysis_incomplete`, dengan `replaced_text` dan `manipulated_regions` kosong, kecuali jika kolom ditemukan pada bagian yang diperiksa.	`poa_document_unproven_text_replacement_action`	Tinjau
`UNSUPPORTED_DOCUMENT_LANGUAGE`	Bahasa dokumen tidak termasuk dalam `poa_languages_allowed`.	`poa_unsupported_language_action`	Tolak
`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`	Jenis dokumen yang terdeteksi tidak diaktifkan dalam `poa_documents_allowed` untuk negara dokumen, atau subjenisnya dinonaktifkan secara eksplisit.	`poa_unsupported_document_type_action`	Tolak
`ISSUER_NOT_IDENTIFIED`	Lembaga penerbit tidak dapat diidentifikasi dari dokumen.	`poa_issuer_not_identified_action`	Tinjau
`UNABLE_TO_EXTRACT_ISSUE_DATE`	Tidak ada tanggal penerbitan yang valid yang dapat ditemukan pada dokumen.	`poa_issue_date_not_detected_action`	Tinjau
`POA_NAME_NOT_DETECTED`	Tidak ada nama yang terdeteksi pada dokumen.	`poa_issue_date_not_detected_action` (opsi bersama)	Tinjau
`UNPARSABLE_OR_INVALID_ADDRESS`	Sebuah alamat berhasil diekstrak, tetapi tidak dapat diurai dan di-geocode menjadi alamat tempat tinggal yang valid.	`poa_unparsable_or_invalid_address_action`	Tinjau
`POA_MAX_ATTEMPTS_EXCEEDED`	Pengguna telah menghabiskan `poa_max_retry_attempts` (bawaan 2) dalam perulangan coba lagi pada alur kerja. `additional_data`: `{ attempts }`. Hanya untuk sesi alur kerja.	`poa_max_attempts_exceeded_action`	Tolak

Ada satu tindakan bersama untuk semua ketidaksesuaian nama dan alamat: poa_name_or_address_mismatch_action mencakup kedua risiko nama, kedua risiko alamat, dan pemeriksaan nama lintas dokumen. Anda tidak dapat mengonfigurasi perilaku ketidaksesuaian nama dan alamat secara terpisah. Pada API mandiri, kelompok yang sama dikendalikan oleh opsi permintaan poa_address_mismatch_action (opsi poa_name_mismatch_action diterima, tetapi tidak pernah dibaca).

Perbedaan API mandiri (`POST /v3/poa/`)

Endpoint mandiri menyusun pemetaan risiko ke tindakan yang sama tetapi dengan opsi tingkat permintaan yang hanya menerima DECLINE atau NO_ACTION (semuanya ber-default DECLINE):

UNABLE_TO_EXTRACT_ISSUE_DATE dan POA_NAME_NOT_DETECTED ditetapkan secara permanen sebagai Tolak pada endpoint ini.
POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION dan UNPARSABLE_OR_INVALID_ADDRESS bersifat informatif di sini — tindakannya secara default adalah Tanpa tindakan dan tidak dapat dikonfigurasi per permintaan.
FUTURE_ISSUE_DATE, POOR_DOCUMENT_QUALITY, NAME_MISMATCH_ID_VERIFICATION, POA_NAME_MISMATCH_BETWEEN_DOCUMENTS, dan POA_MAX_ATTEMPTS_EXCEEDED tidak pernah dihasilkan — dokumen bertanggal masa depan tidak ditolak otomatis pada endpoint ini.

Lihat referensi API POST /v3/poa/ untuk opsi permintaan tersebut.

Perilaku coba lagi (sesi alur kerja)

Dalam sesi verifikasi, langkah unggah POA menjalankan validasi yang memblokir sebelum dokumen diterima. Ketika menemukan kesalahan pemblokiran — INVALID_DOCUMENT_TYPE, UNABLE_TO_EXTRACT_ISSUE_DATE, FUTURE_ISSUE_DATE, POA_NAME_NOT_DETECTED, MISSING_ADDRESS_INFORMATION, POA_COUNTRY_MISMATCH_WITH_PROVIDED, POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION, UNSUPPORTED_DOCUMENT_LANGUAGE, atau POA_DOCUMENT_EXPIRED — pengunggahan ditolak dengan 400 dan kode risiko sebagai pesannya, dan pengguna dapat mencoba lagi dengan dokumen yang lebih baik. Untuk POA_DOCUMENT_EXPIRED, isi respons 400 juga mencakup expiration_reason (printed_expiration atau age_window) sehingga UI Anda dapat menampilkan alasan yang akurat; pada jalur age_window, respons ini juga menyertakan max_age_months. Pada jalur printed_expiration, max_age_months sengaja ditiadakan karena dokumen ditolak berdasarkan tanggal kedaluwarsa yang tercetak, bukan rentang usia dokumen. Setelah pengguna menghabiskan poa_max_retry_attempts percobaan (default 2, dapat dikonfigurasi 2–5), pengiriman dokumen tetap diterima: peringatan yang tersimpan dihitung ulang dari dokumen yang tersimpan, POA_MAX_ATTEMPTS_EXCEEDED ditambahkan, dan status ditentukan dari kumpulan risiko lengkap. Inilah alasan mengapa FUTURE_ISSUE_DATE dapat memblokir pengunggahan namun tidak pernah muncul di warnings[].

Pengaturan yang dapat dikonfigurasi

Node POA dalam alur kerja menyediakan pengaturan berikut (sesuai dengan kolom VerificationSettings):

Pengaturan	Mengontrol	Default
`poa_name_or_address_mismatch_action`	`NAME_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_ID_VERIFICATION`, `ADDRESS_MISMATCH_WITH_PROVIDED`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`	Review
`poa_document_issues_action`	`DOCUMENT_METADATA_MISMATCH`	Review
`poa_document_authenticity_action`	`SUSPECTED_DOCUMENT_MANIPULATION`	Decline
`poa_document_unproven_text_replacement_action`	`POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`	Review (alur kerja yang tidak pernah melakukan peninjauan menggunakan `poa_document_authenticity_action` miliknya sendiri jika bernilai Decline, selain itu No action; API mandiri mengikuti `poa_document_authenticity_action` dari permintaan)
`poa_unsupported_language_action`	`UNSUPPORTED_DOCUMENT_LANGUAGE`	Decline
`poa_unsupported_document_type_action`	`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`	Decline
`poa_issuer_not_identified_action`	`ISSUER_NOT_IDENTIFIED`	Review
`poa_issue_date_not_detected_action`	`UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED`	Review
`poa_unparsable_or_invalid_address_action`	`UNPARSABLE_OR_INVALID_ADDRESS`	Review
`poa_max_attempts_exceeded_action`	`POA_MAX_ATTEMPTS_EXCEEDED`	Decline
`poa_documents_allowed`	Jenis dokumen yang diterima per negara, masing-masing dengan `enabled` dan `age_months` (`-1` = tidak terbatas); penimpaan per subjenis melalui `document_subtypes_config`.	Tagihan utilitas dan rekening koran: 3 bulan; terbitan pemerintah dan lainnya: 12 bulan
`poa_languages_allowed`	Bahasa dokumen yang diterima.	Semua bahasa yang didukung
`poa_name_match_score_threshold`	Skor kecocokan nama minimum (0–100) sebelum risiko `NAME_MISMATCH*` dipicu.	86
`poa_max_retry_attempts`	Percobaan unggah sebelum perulangan coba lagi berhenti (2–5).	2

Logika pencocokan nama

Pencocokan nama POA menoleransi variasi umum:

Nama tengah dan inisial dicocokkan secara fleksibel (keberadaan/ketiadaannya diperbolehkan).
Kandidat nama — setiap nama yang terdeteksi pada dokumen (name_on_document ditambah additional_names) dinilai, dan kandidat dengan skor terbaik dipertahankan.
Ambang batas kecocokan — nilai default poa_name_match_score_threshold adalah 86; skor di bawah nilai ini memicu peringatan NAME_MISMATCH* yang relevan.

Skor numerik ditampilkan dalam laporan sebagai name_match_score_expected_details dan name_match_score_id_verification (0–100). Nilai skor berguna untuk peninjauan terperinci bahkan ketika tidak ada peringatan yang dimunculkan.

Contoh

Manipulasi overlay (Penolakan secara default)

{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "SUSPECTED_DOCUMENT_MANIPULATION",
      "additional_data": {
        "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).",
        "detection_method": "overlay_text_manipulation",
        "signals": ["duplicate_font_subset", "glyph_fragmentation"],
        "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }],
        "fragmented_fonts": [],
        "manipulated_regions": [
          { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 }
        ]
      },
      "log_type": "error",
      "short_description": "Suspected document manipulation",
      "long_description": "The system detected signs of potential document manipulation or editing.",
      "node_id": "feature_poa_1"
    }
  ]
}

Dokumen kedaluwarsa + alamat tidak ada (penolakan otomatis)

{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "POA_DOCUMENT_EXPIRED",
      "additional_data": {
        "expiration_reason": "age_window",
        "max_age_months": 3,
        "document_subtype": "ELECTRICITY_BILL",
        "document_type": "UTILITY_BILL",
        "issue_date": "2025-11-02"
      },
      "log_type": "error",
      "short_description": "Document expired",
      "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity.",
      "node_id": "feature_poa_1"
    },
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "MISSING_ADDRESS_INFORMATION",
      "additional_data": null,
      "log_type": "error",
      "short_description": "Missing address information",
      "long_description": "The document does not contain complete or clear address information that can be extracted.",
      "node_id": "feature_poa_1"
    }
  ]
}

Ketidakcocokan nama (Peninjauan secara default)

{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "NAME_MISMATCH_ID_VERIFICATION",
      "additional_data": {
        "poa_name": "JOHN B SMYTH",
        "kyc_name": "John A. Smith",
        "match_score": 60
      },
      "log_type": "warning",
      "short_description": "Name mismatch with ID verification",
      "long_description": "The full name on the document does not match the name from the user's verified identity documents.",
      "node_id": "feature_poa_1"
    }
  ]
}

Terkait

Laporan Bukti Alamat — bentuk respons lengkap, forensik manipulasi overlay, semantik status
Gambaran umum Bukti Alamat — jenis dokumen yang diterima
Model data — Bukti Alamat — skema kanonikal dan objek Warning
Webhook — status.updated membawa peringatan POA

Autentikasi

Verifikasi

Pemantauan

Platform

Peringatan & Kode Error Bukti Alamat

Gambaran Umum

Dua jalur produksi

Peringatan penolakan otomatis (selalu memaksakan `Declined`)

Peringatan yang dapat dikonfigurasi

Perbedaan API mandiri (`POST /v3/poa/`)

Perilaku coba lagi (sesi alur kerja)

Pengaturan yang dapat dikonfigurasi

Logika pencocokan nama

Contoh

Manipulasi overlay (Penolakan secara default)

Dokumen kedaluwarsa + alamat tidak ada (penolakan otomatis)

Ketidakcocokan nama (Peninjauan secara default)

Terkait

Jenis peringatan

​Gambaran Umum

​Dua jalur produksi

​Peringatan penolakan otomatis (selalu memaksakan Declined)

​Peringatan yang dapat dikonfigurasi

​Perbedaan API mandiri (POST /v3/poa/)

​Perilaku coba lagi (sesi alur kerja)

​Pengaturan yang dapat dikonfigurasi

​Logika pencocokan nama

​Contoh

​Manipulasi overlay (Penolakan secara default)

​Dokumen kedaluwarsa + alamat tidak ada (penolakan otomatis)

​Ketidakcocokan nama (Peninjauan secara default)

​Terkait

​Jenis peringatan

Gambaran Umum

Dua jalur produksi

Peringatan penolakan otomatis (selalu memaksakan `Declined`)

Peringatan yang dapat dikonfigurasi

Perbedaan API mandiri (`POST /v3/poa/`)

Perilaku coba lagi (sesi alur kerja)

Pengaturan yang dapat dikonfigurasi

Logika pencocokan nama

Contoh

Manipulasi overlay (Penolakan secara default)

Dokumen kedaluwarsa + alamat tidak ada (penolakan otomatis)

Ketidakcocokan nama (Peninjauan secara default)

Terkait

Jenis peringatan