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

# 住所証明の警告とエラーコード

> Diditの住所証明(PoA)の全警告コード一覧。氏名の不一致、書類の期限切れ、メタデータの問題、非対応の書類タイプなどを解説。警告ごとに自動却下を設定できます。

## 概要

住所証明(POA)の検証では、抽出およびフォレンジック分析の過程で検出された品質、真正性、照合に関するすべての問題について、`poa_verifications[].warnings[]`に警告が出力されます。各警告は`feature`が`"PROOF_OF_ADDRESS"`に設定された[警告オブジェクト](https://docs.didit.me/ja/reference/data-models.md#警告オブジェクト)です。一部のリスクは常に`Declined`を強制します。それ以外のリスクは、ワークフローで設定したリスクごとのアクション(`DECLINE`/`REVIEW`/`NO_ACTION`)に従います。

以下のすべてのリスクは本番の判定パイプラインで検証済みです。短い説明と長い説明の文字列は、表にそのまま記載しています。

> [!NOTE]
>
> POAの抽出では、書類1件あたり**5〜15秒**のレイテンシが発生します。警告はワークフローのステップが完了した時点でのみ書き込まれます。5秒より短い間隔でポーリングしないでください。

## 本番環境の2つの経路

POAの警告は2つの異なる経路で生成され、経路によって対象となるリスクが異なります。

* **ワークフローセッション**(認証セッション内のPOAステップ):アップロードエンドポイントがまず再試行ループ付きのブロッキング検証を実行します([再試行の動作](#再試行の動作-ワークフローセッション)を参照)。その後、最終的に保存される警告が`check_poa_risks`と複数書類間の氏名チェックによって算出されます。
* **スタンドアロンAPI**(`POST /v3/poa/`):警告は`check_poa_risks`からのみ生成されます。再試行ループも検証済みIDのコンテキストもなく、書類も1件のみのため、`NAME_MISMATCH_ID_VERIFICATION`、`POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`、`POA_MAX_ATTEMPTS_EXCEEDED`、`FUTURE_ISSUE_DATE`がスタンドアロンAPIで生成されることは**決してありません**。この経路では、抽出前の検証エラーは破棄されます。

`POOR_DOCUMENT_QUALITY`はリスクのenumに定義され、アクションのマッピングでも予約されていますが、**POAパイプラインにこれを生成するコードパスはありません**。どちらの経路でも`warnings[]`に含まれることはありません。この値で分岐しないでください。

## 自動却下の警告(常に`Declined`を強制)

これらのリスクは`AUTO_DECLINE_RISKS`に含まれます。記録されると、設定にかかわらずPOAのステータスは`Declined`になり、`log_type`は常に`error`です。

| リスク | 原因 | 推奨される対処 |
| - | - | - |
| `MISSING_ADDRESS_INFORMATION` | 書類から住所を抽出できませんでした。 | 住所がはっきりと記載された書類を再提出するようユーザーに依頼してください。 |
| `POA_DOCUMENT_EXPIRED` | 書類が2つの経路のいずれかで期限切れと判定されました。**記載された有効期限**を過ぎているか、その種類に**設定された最大経過期間を超えている**かのいずれかです。デフォルトは、`UTILITY_BILL`と`BANK_STATEMENT`が**3か月**、`GOVERNMENT_ISSUED_DOCUMENT`と`OTHER_POA_DOCUMENT`が**12か月**です(1か月は30日として計算し、`-1`でチェックを無効化します)。`additional_data`には常に`expiration_reason`(`printed_expiration`または`age_window`)、`document_type`、`document_subtype`、`issue_date`が含まれます。`printed_expiration`の経路では`expiration_date`が、`age_window`の経路では`max_age_months`が追加されます。 | 有効な書類またはより新しい書類をユーザーに依頼するか、その種類の`age_months`を引き上げてください。 |
| `INVALID_DOCUMENT_TYPE` | 書類をサポート対象のPOA書類のいずれの種類にも分類できませんでした(`document_type`は`UNKNOWN`にフォールバックします)。 | ユーザーに再提出を依頼し、ファイルが破損していないか確認してください。 |
| `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | 書類の経過期間チェック自体が失敗しました(発行日から有効期限を算出する際にエラーが発生)。 | 発行日がはっきりと読み取れる書類をユーザーに依頼してください。 |

`FUTURE_ISSUE_DATE`も`AUTO_DECLINE_RISKS`に含まれていますが、生成元は抽出前の検証(発行日が7日より先の日付である場合)の1つだけで、そのエラーは**ワークフローの再試行ループ**にのみ渡されます。そこではアップロード時のブロッキングエラーとして表示され、スタンドアロンAPIでは生成されず、`warnings[]`にも書き込まれません。[再試行の動作](#再試行の動作-ワークフローセッション)を参照してください。

## 設定可能な警告

以下の警告は、いずれもワークフローのPOAノードにあるアクション設定（`DECLINE` / `REVIEW` / `NO_ACTION`）に従います。警告の`log_type`は設定されたアクションに対応し、拒否の場合は`error`、レビューの場合は`warning`、アクションなしの場合は`information`になります。

| リスク | 原因 | アクション設定 | デフォルト |
| - | - | - | - |
| `NAME_MISMATCH_WITH_PROVIDED` | 書類上の氏名と、セッション作成時に指定された氏名（`expected_details`）を照合したスコアが`poa_name_match_score_threshold`（デフォルト86）を下回りました。 | `poa_name_or_address_mismatch_action` | レビュー |
| `NAME_MISMATCH_ID_VERIFICATION` | 書類上の氏名と、検証済みの本人確認書類の氏名を照合したスコアがしきい値を下回りました。`additional_data`：`{ poa_name, kyc_name, match_score }`。ワークフローセッションのみ。 | `poa_name_or_address_mismatch_action` | レビュー |
| `ADDRESS_MISMATCH_WITH_PROVIDED` | 抽出された住所がAPI経由で指定された住所と異なるか、いずれかの住所を居住用住所として検証できませんでした。 | `poa_name_or_address_mismatch_action` | レビュー |
| `POA_COUNTRY_MISMATCH_WITH_PROVIDED` | 書類の国が、API経由で指定された国（ISO-3形式に正規化）と一致しません。`additional_data`：`{ expected_country, extracted_country }`。 | `poa_name_or_address_mismatch_action` | レビュー |
| `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | 同じセッション内の2つ以上のPOA書類で、記載された氏名が異なります。`additional_data`には両方のノードID、両方の氏名、一致スコアが含まれます。ワークフローセッションのみ。 | `poa_name_or_address_mismatch_action` | レビュー |
| `DOCUMENT_METADATA_MISMATCH` | ファイルが空（`file_size`が0）であるか、EXIFの日付の形式が不正です。 | `poa_document_issues_action` | レビュー |
| `SUSPECTED_DOCUMENT_MANIPULATION` | フォレンジック分析で改ざんの証拠が見つかりました。具体的には、電子署名後の変更（`is_tampered`）、重ね書きテキストによる改ざん（`additional_data.manipulated_regions`の矩形領域を含む）、既知のPDF編集ソフトの使用、EXIFの日付の不整合、不審な再エクスポートのいずれかです。`additional_data.detection_method`には検出したチェックの名前が入ります。 | `poa_document_authenticity_action` | **拒否** |
| `UNSUPPORTED_DOCUMENT_LANGUAGE` | 書類の言語が`poa_languages_allowed`に含まれていません。 | `poa_unsupported_language_action` | **拒否** |
| `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | 検出された書類の種類が、その書類の国について`poa_documents_allowed`で有効になっていないか、そのサブタイプが明示的に無効化されています。 | `poa_unsupported_document_type_action` | **拒否** |
| `ISSUER_NOT_IDENTIFIED` | 書類から発行機関を特定できませんでした。 | `poa_issuer_not_identified_action` | レビュー |
| `UNABLE_TO_EXTRACT_ISSUE_DATE` | 書類上で有効な発行日を見つけられませんでした。 | `poa_issue_date_not_detected_action` | レビュー |
| `POA_NAME_NOT_DETECTED` | 書類上で氏名が検出されませんでした。 | `poa_issue_date_not_detected_action`（共通の設定） | レビュー |
| `UNPARSABLE_OR_INVALID_ADDRESS` | 住所は抽出されましたが、有効な居住用住所として解析およびジオコーディングできませんでした。 | `poa_unparsable_or_invalid_address_action` | レビュー |
| `POA_MAX_ATTEMPTS_EXCEEDED` | ユーザーがワークフローの再試行ループで`poa_max_retry_attempts`（デフォルト2）を使い切りました。`additional_data`：`{ attempts }`。ワークフローセッションのみ。 | `poa_max_attempts_exceeded_action` | **拒否** |

> [!NOTE]
>
> 氏名と住所の不一致には、すべて**単一の共通アクション**が適用されます。`poa_name_or_address_mismatch_action`は、氏名に関する2つのリスク、住所に関する2つのリスク、書類間の氏名チェックをすべて対象とするため、氏名の不一致と住所の不一致の動作を個別に設定することはできません。スタンドアロンAPIでは、同じグループが`poa_address_mismatch_action`リクエストオプションに従います（`poa_name_mismatch_action`オプションは受け付けられますが、参照されることはありません）。

## スタンドアロンAPIとの違い (`POST /v3/poa/`)

スタンドアロンのエンドポイントも同じリスクとアクションの対応付けを構築しますが、リクエスト単位のオプションは`DECLINE`または`NO_ACTION`のみを受け付けます（いずれもデフォルトは`DECLINE`）。

* このエンドポイントでは、`UNABLE_TO_EXTRACT_ISSUE_DATE`と`POA_NAME_NOT_DETECTED`は**却下に固定**されています。
* ここでは`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`と`UNPARSABLE_OR_INVALID_ADDRESS`は**情報提供のみ**です。これらのアクションのデフォルトはアクションなしで、リクエストごとに設定することはできません。
* `FUTURE_ISSUE_DATE`、`POOR_DOCUMENT_QUALITY`、`NAME_MISMATCH_ID_VERIFICATION`、`POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`、`POA_MAX_ATTEMPTS_EXCEEDED`は生成されません。そのため、このエンドポイントでは発行日が将来の日付の書類は自動的に**却下されません**。

リクエストオプションについては、[POST /v3/poa/ APIリファレンス](https://docs.didit.me/ja/standalone-apis/proof-of-address.md)を参照してください。

## 再試行の動作 (ワークフローセッション)

検証セッションでは、POAのアップロードステップで書類を受け付ける前にブロッキング検証を実行します。`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`、`POA_DOCUMENT_EXPIRED`のいずれかのブロッキングエラーが見つかった場合、アップロードは`400`で拒否され、メッセージとしてリスクコードが返されます。ユーザーはより適切な書類で再試行できます。

`POA_DOCUMENT_EXPIRED`の場合、`400`のボディには`expiration_reason`（`printed_expiration`または`age_window`）も含まれるため、UIで正確な理由を表示できます。`age_window`の場合は、さらに`max_age_months`も含まれます。`printed_expiration`の場合は、書類が経過期間ではなく印字された有効期限を理由に拒否されたため、`max_age_months`は意図的に省略されます。

ユーザーが`poa_max_retry_attempts`回（デフォルト2、2〜5の範囲で設定可能）の試行を使い切ると、提出はそのまま受け付けられます。保存された書類から警告が再計算され、`POA_MAX_ATTEMPTS_EXCEEDED`が追加されたうえで、すべてのリスクコードに基づいてステータスが決定されます。このため、`FUTURE_ISSUE_DATE`はアップロードをブロックすることはあっても、`warnings[]`に表示されることはありません。

## 設定可能な項目

ワークフローのPOAノードでは、次の設定を調整できます(`VerificationSettings`のフィールドに対応しています)。

| 設定 | 対象 | デフォルト |
| - | - | - |
| `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` | レビュー |
| `poa_document_issues_action` | `DOCUMENT_METADATA_MISMATCH` | レビュー |
| `poa_document_authenticity_action` | `SUSPECTED_DOCUMENT_MANIPULATION` | 却下 |
| `poa_unsupported_language_action` | `UNSUPPORTED_DOCUMENT_LANGUAGE` | 却下 |
| `poa_unsupported_document_type_action` | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | 却下 |
| `poa_issuer_not_identified_action` | `ISSUER_NOT_IDENTIFIED` | レビュー |
| `poa_issue_date_not_detected_action` | `UNABLE_TO_EXTRACT_ISSUE_DATE`、`POA_NAME_NOT_DETECTED` | レビュー |
| `poa_unparsable_or_invalid_address_action` | `UNPARSABLE_OR_INVALID_ADDRESS` | レビュー |
| `poa_max_attempts_exceeded_action` | `POA_MAX_ATTEMPTS_EXCEEDED` | 却下 |
| `poa_documents_allowed` | 国ごとに受け付ける書類タイプ。各タイプに`enabled`と`age_months`(`-1`=無制限)を指定します。サブタイプごとの上書きは`document_subtypes_config`で行います。 | 公共料金の請求書と銀行取引明細書は3か月、政府発行書類とその他は12か月 |
| `poa_languages_allowed` | 受け付ける書類の言語。 | サポート対象のすべての言語 |
| `poa_name_match_score_threshold` | `NAME_MISMATCH*`のリスクが発生するまでの氏名一致スコアの最小値(0〜100)。 | 86 |
| `poa_max_retry_attempts` | 再試行ループが終了するまでのアップロード試行回数(2〜5)。 | 2 |

## 氏名照合のロジック

POAの氏名照合では、よくある表記の揺れを許容します。

* **ミドルネームとイニシャル**は緩やかに照合されます(有無のどちらも許容されます)。
* **候補となる氏名**:書類から検出されたすべての氏名(`name_on_document`と`additional_names`)をスコアリングし、最もスコアの高い候補を採用します。
* **一致のしきい値**:`poa_name_match_score_threshold`のデフォルトは**86**です。スコアがこれを下回ると、該当する`NAME_MISMATCH*`警告が発生します。

数値スコアは、レポート上で`name_match_score_expected_details`と`name_match_score_id_verification`(0〜100)として表示されます。スコアの値は、警告が発生していない場合でも、きめ細かなレビューに役立ちます。

## 例

### オーバーレイによる改ざん(デフォルトは却下)

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

### 期限切れの書類と住所の欠落(自動却下)

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

### 氏名の不一致(デフォルトはレビュー)

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

## 関連ページ

* [住所証明レポート](https://docs.didit.me/ja/core-technology/proof-of-address/report-proof-of-address.md):レスポンスの全体構造、オーバーレイ改ざんのフォレンジック、ステータスの意味
* [住所証明の概要](https://docs.didit.me/ja/core-technology/proof-of-address/overview.md):受け付ける書類タイプ
* [データモデル:住所証明](https://docs.didit.me/ja/reference/data-models.md#住所証明):正規のスキーマとWarningオブジェクト
* [Webhook](https://docs.didit.me/ja/integration/webhooks.md):`status.updated`にPOAの警告が含まれます

### 警告タイプ


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