메인 콘텐츠로 건너뛰기

개요

주소 증명(POA) 인증은 추출 및 포렌식 분석 중에 감지된 모든 품질, 진위 여부 또는 일치 문제에 대해 poa_verifications[].warnings[]에 경고를 생성합니다. 각 경고는 feature가 "PROOF_OF_ADDRESS"로 설정된 경고 객체입니다. 몇 가지 위험은 항상 강제로 Declined 처리를 유발하며, 나머지는 워크플로에 설정된 위험별 작업(DECLINE / REVIEW / NO_ACTION)을 따릅니다. 아래의 모든 위험은 실제 프로덕션 의사 결정 파이프라인과 대조하여 검증되었습니다. 표에는 정확한 짧은 설명 및 긴 설명 문자열이 그대로 재현되어 있습니다.
POA 추출에는 문서당 5–15초의 지연 시간이 발생합니다. 경고는 워크플로 단계가 완료될 때만 기록되므로, 5초보다 빠른 주기로 폴링하지 마십시오.

두 가지 프로덕션 경로

POA 경고는 두 가지 서로 다른 경로에서 생성되며, 경로에 따라 위험 세트가 다릅니다:
  • 워크플로 세션(인증 세션 내부의 POA 단계) — 업로드 endpoint는 먼저 재시도 루프(참조: 재시도 동작)와 함께 차단 유효성 검사를 실행한 다음, check_poa_risks와 다중 문서 이름 확인을 통해 최종 저장될 경고를 계산합니다.
  • 독립형 API(POST /v3/poa/) — 경고는 check_poa_risks에서만 생성됩니다. 재시도 루프가 없고, 인증된 신분증 컨텍스트가 없으며, 문서가 하나뿐이므로 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입니다. FUTURE_ISSUE_DATE도 AUTO_DECLINE_RISKS에 나열되어 있지만, 추출 전 유효성 검사(발급일이 현재 날짜보다 7일을 초과하여 미래인 경우)에서 단 하나의 생성 경로만 가집니다. 해당 오류는 워크플로 재시도 루프에만 전달되어 차단 업로드 오류로 나타나며, 독립형 API에서는 절대 생성되지 않고 warnings[]에 기록되지도 않습니다. 참조: 재시도 동작.

구성 가능한 경고

각 경고는 워크플로의 POA 노드에 있는 작업 설정(DECLINE / REVIEW / NO_ACTION) 중 하나를 따릅니다. 경고의 log_type은 구성된 작업과 일치합니다. 거부는 error, 검토는 warning, 조치 없음은 information에 해당합니다.
모든 이름 및 주소 불일치에는 하나의 공통 작업이 적용됩니다. poa_name_or_address_mismatch_action이 두 이름 위험, 두 주소 위험, 문서 간 이름 검사를 모두 담당하므로 이름 불일치와 주소 불일치의 동작을 따로 구성할 수 없습니다. 독립형 API에서는 같은 그룹이 poa_address_mismatch_action 요청 옵션을 따릅니다(poa_name_mismatch_action 옵션은 허용되지만 읽히지 않습니다).

독립 실행형 API 차이점 (POST /v3/poa/)

독립 실행형 endpoint는 동일한 위험-작업 매핑을 구성하지만, DECLINE 또는 NO_ACTION만 허용하는 요청 수준 옵션을 사용합니다(모두 기본값은 DECLINE).
  • UNABLE_TO_EXTRACT_ISSUE_DATE 및 POA_NAME_NOT_DETECTED는 이 endpoint에서 거부로 하드코딩되어 있습니다.
  • 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는 발생하지 않으며, 미래 날짜로 작성된 문서는 이 endpoint에서 자동으로 거부되지 않습니다.
요청 옵션에 대해서는 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_on_document 및 additional_names)에 대해 점수가 매겨지며, 가장 높은 점수를 받은 후보가 유지됩니다.
  • 일치 임계값 — 기본 poa_name_match_score_threshold는 86입니다. 이보다 낮은 점수는 관련 NAME_MISMATCH* 경고를 트리거합니다.
숫자 점수는 보고서에 name_match_score_expected_details 및 name_match_score_id_verification(0–100)으로 표시됩니다. 점수 값은 경고가 발생하지 않은 경우에도 정밀한 검토에 유용합니다.

예시

오버레이 조작(기본값: 거부)

만료된 문서 및 주소 누락(자동 거부)

이름 불일치(기본값: 검토)

관련 항목

경고 유형

마지막 수정일 2026년 11월 7일