> ## 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.

# Peringatan & Kode Error Bukti Alamat

> Semua kode peringatan Bukti Alamat Didit: nama tidak cocok, dokumen kedaluwarsa, & lainnya. Konfigurasikan penolakan otomatis per peringatan.

## 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](https://docs.didit.me/id/reference/data-models.md#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.

> [!NOTE]
>
> 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](#perilaku-coba-lagi-sesi-alur-kerja)), 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](#perilaku-coba-lagi-sesi-alur-kerja).

## 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** |

> [!NOTE]
>
> 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/](https://docs.didit.me/id/standalone-apis/proof-of-address.md) 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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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](https://docs.didit.me/id/core-technology/proof-of-address/report-proof-of-address.md) — bentuk respons lengkap, forensik manipulasi overlay, semantik status
* [Gambaran umum Bukti Alamat](https://docs.didit.me/id/core-technology/proof-of-address/overview.md) — jenis dokumen yang diterima
* [Model data — Bukti Alamat](https://docs.didit.me/id/reference/data-models.md#bukti-alamat) — skema kanonikal dan objek Warning
* [Webhook](https://docs.didit.me/id/integration/webhooks.md) — `status.updated` membawa peringatan POA

### Jenis peringatan


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.