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

概要

住所証明(POA)の検証では、抽出およびフォレンジック分析の過程で検出された品質、真正性、照合に関するすべての問題について、poa_verifications[].warnings[]に警告が出力されます。各警告はfeatureが"PROOF_OF_ADDRESS"に設定された警告オブジェクトです。一部のリスクは常にDeclinedを強制します。それ以外のリスクは、ワークフローで設定したリスクごとのアクション(DECLINE/REVIEW/NO_ACTION)に従います。以下のすべてのリスクは本番の判定パイプラインで検証済みです。短い説明と長い説明の文字列は、表にそのまま記載しています。

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`	拒否

氏名と住所の不一致には、すべて単一の共通アクションが適用されます。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リファレンスを参照してください。

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

検証セッションでは、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)として表示されます。スコアの値は、警告が発生していない場合でも、きめ細かなレビューに役立ちます。

例

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

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

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

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

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

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

認証

検証

モニタリング

プラットフォーム

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

概要

本番環境の2つの経路

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

設定可能な警告

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

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

設定可能な項目

氏名照合のロジック

例

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

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

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

関連ページ

警告タイプ

​概要

​本番環境の2つの経路

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

​設定可能な警告

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

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

​設定可能な項目

​氏名照合のロジック

​例

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

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

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

​関連ページ

​警告タイプ

概要

本番環境の2つの経路

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

設定可能な警告

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

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

設定可能な項目

氏名照合のロジック

例

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

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

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

関連ページ

警告タイプ