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

# 기업 확인 경고 및 KYB 오류 코드

> Didit 기업 확인 경고 코드를 KYB 등록부, KYB 문서, 주요 인물, AML, 전화번호, 이메일, 설문지, 기기 및 IP 분석 기능별로 정리합니다.

기업 확인(KYB)이 경고를 생성한 기능 항목에 경고를 표시합니다. 각 경고는 플랫폼 전반에서 사용하는 표준 구조화 형식인 `feature`, `risk`, `log_type`, `short_description`, `long_description`, 선택 항목인 `additional_data`, 그리고 `node_id`를 포함하므로, 검토 업무를 적절한 운영 팀에 전달할 수 있습니다.

## 개요

KYB 세션은 V3 결정 응답의 전용 기능 배열에 대응하는 세 가지 핵심 기능 태그로 경고를 생성합니다.

| 기능 태그 | 결정 응답 키 | 다루는 내용 |
| - | - | - |
| `KYB_REGISTRY` | `registry_checks[].warnings[]` | 공식 법인 등기부 조회. 활성 상태, 국가 제한, 도출 가능한 소유 구조, 임원 또는 UBO 기록 누락. |
| `KYB_DOCUMENTS` | `document_verifications[].warnings[]` | 사용자가 업로드한 설립, 소유 구조, 주소, 주주 문서. 문서 간 일관성, OCR, 메타데이터, 변조, 연령 및 하위 유형 규칙. |
| `KYB_KEY_PEOPLE` | `key_people_checks[].warnings[]` | 이사, 임원, UBO 또는 사용자가 제출한 당사자에 대한 개인별 신호. AML 및 이전 거부 건 재사용에서 전파된 정치적 주요 인물(PEP) 및 제재 결과 포함. |

동일한 KYB 워크플로에는 아래의 공통 기능도 포함될 수 있습니다. 이 기능들은 자체 배열에 경고를 생성합니다.

| 기능 태그 | 결정 응답 키 |
| - | - |
| `AML` | `aml_screenings[].warnings[]` |
| `PHONE` | `phone_verifications[].warnings[]` |
| `EMAIL` | `email_verifications[].warnings[]` |
| `QUESTIONNAIRE` | `questionnaire_responses` (경고는 세션 로그에 있습니다) |
| `LOCATION` | `ip_analyses[].warnings[]` |

## KYB 법인 등기부 경고

법인 등기부 경고는 `feature: "KYB_REGISTRY"`를 사용하며 `registry_checks[].warnings[]`에 표시됩니다.

| 태그 | 설명 |
| - | - |
| `KYB_COUNTRY_RESTRICTED` | 회사의 국가가 워크플로에 설정된 허용 국가 목록에 포함되지 않습니다. |
| `KYB_OFFICERS_DATA_NOT_FOUND` | 등기부에서 임원 데이터를 사용할 수 없습니다. |
| `KYB_OWNERSHIP_DATA_NOT_FOUND` | 등기부에서 소유 데이터를 사용할 수 없습니다. |
| `KYB_BENEFICIAL_OWNERSHIP_NOT_DERIVABLE` | 등기부 데이터로는 최종 실소유권을 확인할 수 없습니다. |
| `KYB_COMPANY_NOT_ACTIVE` | 등기부 기준으로 회사가 활동 중이 아닙니다. |
| `KYB_COMPANY_NOT_FROM_REGISTRY` | 회사가 수동으로 입력되었으며 법인 등기부에서 확인할 수 없습니다. |
| `KYB_REGISTRY_DATA_MISMATCH_WITH_EXPECTED` | 법인 등기부에서 확인된 회사의 등록번호가 세션 생성 시 보낸 `expected_details.registration_number`와 일치하지 않습니다. |
| `KYB_REGISTRY_DATA_PARTIAL_MATCH_WITH_EXPECTED` | 법인 등기부에서 확인된 등록번호가 예상 번호와 일부만 일치합니다. 예를 들어 지점 또는 자회사 접미사가 있는 경우입니다. |
| `KYB_COMPANY_VAT_INVALID` | 공식 세무 등록부에 회사의 VAT 번호 또는 납세자 번호에 대한 활성 등록이 없거나, VAT 번호가 해당 국가의 형식 및 검증 숫자 규칙을 충족하지 않습니다. 설정된 `kyb_vat_invalid_action`이 적용됩니다(기본값: 검토 중). |
| `KYB_COMPANY_VAT_COULD_NOT_VALIDATE` | 공식 등기부가 일시적으로 사용할 수 없어 VAT 번호 또는 납세자 번호를 검증할 수 없습니다. 설정된 `kyb_vat_unverified_action`이 적용됩니다(기본값: 영향 없음). |
| `KYB_COMPANY_VAT_NAME_MISMATCH` | 이 번호에 대해 공식 등기부에 등록된 이름이 제출된 회사명과 다릅니다. 참고용 정보이며, `additional_data`에 `registry_name`, `registry_source`, `submitted_name`이 포함되고, 등기부가 VIES인 경우 `vies_name`도 포함됩니다. |

VAT 경고는 회사의 VAT 번호 또는 납세자 번호를 검증할 수 있는 모든 경우에 적용됩니다. 해당 국가와 출처는 [VAT 및 납세자 번호 검증](https://docs.didit.me/ko/business-verification/company-data.md#vat-및-납세자-번호-검증)을 참고하세요.

## KYB 문서 경고

문서 경고는 `feature: "KYB_DOCUMENTS"`를 사용하며 `document_verifications[].warnings[]`에 표시됩니다.

| 태그 | 설명 |
| - | - |
| `KYB_DOCUMENT_MISSING_REQUIRED_FIELD` | 기업명이나 등록번호처럼 필수 기업 필드를 문서에서 찾지 못했습니다. |
| `KYB_DOCUMENT_NAME_MISMATCH` | 문서의 기업명이 법인 등기부와 일치하지 않습니다. |
| `KYB_DOCUMENT_REG_NUMBER_MISMATCH` | 문서의 등록번호가 법인 등기부와 일치하지 않습니다. |
| `KYB_DOCUMENT_INCORPORATION_DATE_MISMATCH` | 문서의 설립일이 법인 등기부와 일치하지 않습니다. |
| `KYB_DOCUMENT_ADDRESS_MISMATCH` | 문서의 등록 주소가 법인 등기부와 일치하지 않습니다. |
| `KYB_CROSS_DOCUMENT_MISMATCH` | 업로드된 법인 문서 간에 기업 정보가 서로 다릅니다. |
| `KYB_DOCUMENT_METADATA_MISMATCH` | 문서의 서명, 메타데이터 또는 파일 구조에 문제가 있을 가능성이 있음을 나타냅니다. |
| `KYB_ASSOCIATED_PARTY_MISMATCH` | 문서의 이사 또는 주주가 법인 등기부와 일치하지 않습니다. |
| `KYB_DOCUMENT_GRAPHIC_EDITOR` | 문서가 그래픽 편집 소프트웨어로 처리된 것으로 보입니다. |
| `KYB_DOCUMENT_SUSPECTED_MANIPULATION` | 시스템이 법인 문서가 변조되었을 가능성의 징후를 감지했습니다. |
| `KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | 법인 문서의 텍스트 필드가 지워진 뒤 다른 글꼴로 다시 입력되었으나, 파일에는 내용이 변경되었는지 여부를 증명할 자료가 없습니다. 전체를 검사할 수 없었던 파일에도 이 경고가 발생하며, 이때 `additional_data.detection_method`는 `analysis_incomplete`로 설정됩니다. 검사하지 못한 부분에 이러한 필드가 있을 수 있기 때문입니다. 이 경고는 `kyb_document_unproven_text_replacement_action` 설정을 따르며, 기본값은 Review입니다. 검토를 하지 않는 워크플로는 `kyb_document_tampering_action`이 Decline으로 설정된 경우 이 값을 사용하고, 그렇지 않으면 No action을 적용합니다. |
| `KYB_ADDITIONAL_DATA_NOT_FOUND` | 해당하는 법인 등기부 데이터를 사용할 수 없어 문서 필드를 검증하지 못했습니다. |
| `KYB_DOCUMENT_EXPIRED` | 법인 문서가 설정된 최대 허용 기간을 초과했습니다. |
| `KYB_DOCUMENT_UNSUPPORTED_SUBTYPE` | 업로드된 문서의 하위 유형이 해당 워크플로에서 비활성화되어 있습니다. |
| `KYB_DOCUMENT_MAX_ATTEMPTS_EXCEEDED` | 법인 문서 업로드 시도 횟수의 최대치를 초과했습니다. |

PDF 오버레이 텍스트 변조의 경우 `KYB_DOCUMENT_SUSPECTED_MANIPULATION`에 `additional_data.manipulated_regions`가 포함될 수 있습니다. 텍스트 필드가 지워진 뒤 다른 글꼴로 다시 입력되면 `KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`가 발생하며, 이때도 `manipulated_regions` 형식은 동일합니다. 단독으로 `KYB_DOCUMENT_SUSPECTED_MANIPULATION`이 발생하지는 않습니다. 온라인 편집기는 변경하지 않은 텍스트도 다시 입력하기 때문에, 이 경고는 내용이 변경되었다는 뜻이 아닙니다. 같은 문서에서 다른 신호로 `KYB_DOCUMENT_SUSPECTED_MANIPULATION`이 발생하면 두 작업 중 더 엄격한 작업이 적용됩니다. 이 영역들은 의심되는 편집 영역을 나타내는 페이지 좌표상의 사각형이며, `document_verifications[].items[].document_metadata.overlay_manipulation.manipulated_regions`에 반환되는 사각형과 일치합니다.

## KYB 주요 인물 경고

주요 인물 경고는 `feature: "KYB_KEY_PEOPLE"`를 사용하며, `key_people_checks[].warnings[]`에 표시됩니다. 이 경고는 이사, 임원, UBO, 사용자가 제출한 당사자에 대한 개인 단위 문제를 알려 줍니다.

| 태그 | 설명 |
| - | - |
| `KYB_PREVIOUSLY_DECLINED_INDIVIDUAL` | 같은 애플리케이션에 대한 다른 기업 확인(KYB)에서 해당 회사와 관련된 사람이 이전에 거부되었습니다. |
| `KYB_KEY_PEOPLE_MISMATCH_WITH_DOCUMENTS` | 주요 인물 화면에 신고된 이사 또는 주주가 업로드된 법인 문서에 나온 사람들과 일치하지 않습니다. 문서에 나온 사람이 신고되지 않았거나, 이름이 거의 일치하거나, 문서상 주주가 소유권 역할 없이 신고되었거나, 신고된 지분율이 문서와 모순되는 경우입니다. 설정된 `kyb_key_people_document_mismatch_action`이 적용됩니다(기본값: In Review). |

> [!NOTE]
>
> **정치적 주요 인물(PEP) 및 제재 일치 항목**은 KYB 주요 인물 경고가 아니라, 해당하는 `aml_screenings[]` 항목에 일반 AML 일치 항목으로 보고됩니다. 주요 인물 검사는 그 결과로 나온 `Declined` 또는 `In Review` 상태를 영향을 받은 각 당사자에게 전파하여, 주요 인물 전체 판정이 AML 결과를 반영하도록 합니다.

## 공통 기능 경고

아래 기능은 KYB 워크플로 안에서 실행될 수 있습니다. 사용자 인증과 동일한 경고 카탈로그를 사용하며, 각 기능의 전체 참조는 해당 기능의 경고 페이지에서 확인할 수 있습니다.

### AML

`feature: "AML"`, `aml_screenings[].warnings[]`에 표시됩니다.

| 태그 | 설명 |
| - | - |
| `POSSIBLE_MATCH_FOUND` | AML 스크리닝에서 검토가 필요한 가능성 있는 일치 항목이 발견되었습니다. |
| `COULD_NOT_PERFORM_AML_SCREENING` | 필수 스크리닝 데이터가 누락되었거나 사용할 수 없어 Didit이 AML 스크리닝을 수행하지 못했습니다. |

### 전화번호

`feature: "PHONE"`, `phone_verifications[].warnings[]`에 표시됩니다.

| 태그 | 설명 |
| - | - |
| `DISPOSABLE_NUMBER_DETECTED` | 전화번호가 일회용 번호입니다. |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | 인증 코드 입력 최대 시도 횟수를 초과했습니다. |
| `VOIP_NUMBER_DETECTED` | 전화번호가 VoIP 번호입니다. |
| `DUPLICATED_PHONE_NUMBER` | 해당 전화번호가 다른 인증 프로세스에서 사용되었습니다. |
| `HIGH_RISK_PHONE_NUMBER` | 전화번호의 위험 수준이 높습니다. |
| `PHONE_NUMBER_IN_BLOCKLIST` | 전화번호가 차단 목록의 항목과 일치합니다. |

### 이메일

`feature: "EMAIL"`, `email_verifications[].warnings[]`에 표시됩니다.

| 태그 | 설명 |
| - | - |
| `BREACHED_EMAIL_DETECTED` | 이메일 주소가 알려진 데이터 유출 사고에 포함되어 있습니다. |
| `DISPOSABLE_EMAIL_DETECTED` | 이메일 주소가 일회용 주소입니다. |
| `UNDELIVERABLE_EMAIL_DETECTED` | 이메일 주소로 메일을 전달할 수 없습니다. |
| `DUPLICATED_EMAIL` | 해당 이메일 주소가 다른 인증 프로세스에서 사용되었습니다. |
| `EMAIL_IN_BLOCKLIST` | 이메일 주소가 차단 목록의 항목과 일치합니다. |
| `EMAIL_CODE_ATTEMPTS_EXCEEDED` | 이메일 인증 코드 입력 최대 시도 횟수를 초과했습니다. |

### 설문지

`feature: "QUESTIONNAIRE"`에 표시됩니다.

| 태그 | 설명 |
| - | - |
| `CUSTOM_STATUS_RULE_TRIGGERED` | 워크플로 상태 규칙이 설문지 답변을 평가하여 기능 상태를 변경했습니다. |

### 기기 및 IP 분석

`feature: "LOCATION"`, `ip_analyses[].warnings[]`에 표시됩니다.

| 태그 | 설명 |
| - | - |
| `COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP` | 문서상의 국가와 IP 주소의 국가가 일치하지 않습니다. |
| `PRIVATE_NETWORK_DETECTED` | 사설 네트워크, VPN, 프록시 또는 Tor 신호가 감지되었습니다. |
| `EXPECTED_IP_ADDRESS_MISMATCH` | IP 주소가 세션에 제공된 예상 IP 주소와 일치하지 않습니다. |
| `IP_ADDRESS_IN_BLOCKLIST` | IP 주소가 차단 목록의 항목과 일치합니다. |
| `DEVICE_FINGERPRINT_IN_BLOCKLIST` | 기기 지문이 차단 목록의 항목과 일치합니다. |
| `DUPLICATED_IP_ADDRESS` | 다른 `vendor_data`를 사용하는 인증에서 같은 IP 주소가 사용되었습니다. |
| `DUPLICATED_DEVICE_FINGERPRINT` | 다른 `vendor_data`를 사용하는 인증에서 같은 기기 지문이 사용되었습니다. |

## 예시

### 레지스트리 — 회사가 활성 상태가 아님

```json theme={null}
{
  "registry_checks": [
    {
      "node_id": "feature_kyb_registry",
      "status": "Declined",
      "warnings": [
        {
          "feature": "KYB_REGISTRY",
          "risk": "KYB_COMPANY_NOT_ACTIVE",
          "log_type": "error",
          "short_description": "Company is not active",
          "long_description": "The company is not active according to the registry.",
          "additional_data": null,
          "node_id": "feature_kyb_registry"
        }
      ]
    }
  ]
}
```

### 문서 — 오버레이 조작 의심

```json theme={null}
{
  "document_verifications": [
    {
      "node_id": "feature_kyb_documents",
      "status": "In Review",
      "warnings": [
        {
          "feature": "KYB_DOCUMENTS",
          "risk": "KYB_DOCUMENT_SUSPECTED_MANIPULATION",
          "log_type": "warning",
          "short_description": "Possible document manipulation",
          "long_description": "The system detected signs of possible corporate-document manipulation.",
          "additional_data": {
            "manipulated_regions": [
              { "page": 1, "x": 120, "y": 240, "width": 180, "height": 22, "page_width": 612, "page_height": 792 }
            ]
          },
          "node_id": "feature_kyb_documents"
        }
      ]
    }
  ]
}
```

### 주요 인물 — 이전에 거부된 개인

```json theme={null}
{
  "key_people_checks": [
    {
      "node_id": "feature_kyb_key_people",
      "status": "In Review",
      "warnings": [
        {
          "feature": "KYB_KEY_PEOPLE",
          "risk": "KYB_PREVIOUSLY_DECLINED_INDIVIDUAL",
          "log_type": "warning",
          "short_description": "Previously declined individual",
          "long_description": "A person associated with the company was previously declined in another business verification for the same application.",
          "additional_data": null,
          "node_id": "feature_kyb_key_people"
        }
      ]
    }
  ]
}
```

## 관련 문서

> [card] [응답 스키마](https://docs.didit.me/ko/business-verification/response-schema.md)
>
> KYB 기능 배열 각각에서 경고가 표시되는 위치를 확인합니다.

> [card] [상태](https://docs.didit.me/ko/business-verification/statuses.md)
>
> 경고 심각도가 인증 상태에 어떻게 매핑되는지 이해합니다.

> [card] [문서](https://docs.didit.me/ko/business-verification/documents.md)
>
> 문서 그룹, OCR 및 교차 검증 동작을 검토합니다.

> [card] [주요 인물](https://docs.didit.me/ko/business-verification/key-people.md)
>
> 임원, 실소유자 및 제출 당사자 인증 흐름을 확인합니다.

> [card] [AML 보고서](https://docs.didit.me/ko/core-technology/aml-screening/report-aml-screening.md)
>
> 회사 및 개인 AML 스크리닝의 히트 단위 구조를 확인합니다.

> [card] [참조 데이터 모델](https://docs.didit.me/ko/reference/data-models.md)
>
> 경고와 기능 배열의 표준 구조를 확인합니다.


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