데이터베이스 검증 경고 및 건너뛰기 코드

Didit의 데이터베이스 검증 기능은 공신력 있는 주민등록기관(아르헨티나의 RENAPER, 브라질의 Receita Federal, 파나마의 Tribunal Electoral(생체 인식), 도미니카 공화국의 Junta Central Electoral 등)을 통해 신원 데이터를 검증하며, 월 최소 청구 금액 없이 성공한 쿼리 건당 청구됩니다. 어떤 서비스도 실행될 수 없거나(필수 필드 누락 또는 형식 오류, 등록기관 사용 불가), 문서 자체를 확인할 수 없거나(구성된 서비스에 필요한 식별자가 없는 경우 — 예: 주민등록번호가 없는 여권), 종합된 결과가 확정적이지 않은 경우(부분 일치, 일치하지 않음) 해당 기능은 세션에 경고를 발생시킵니다. 워크플로에서 발급 국가가 아예 활성화되어 있지 않은 경우, 이 단계는 경고나 비용 청구 없이 건너뜁니다. 이 페이지에서는 모든 경고 코드, 트리거 조건 및 워크플로 응답 구성 방법을 설명합니다.

개요

경고는 워크플로 세션과 독립형 API(POST /v3/database-validation/) 모두에서 생성됩니다. 5가지 위험은 모두 DATABASE_VALIDATION 기능으로 태그 지정되며 보고서의 database_validations[].warnings[] 아래에 표시되고, 표준 경고 객체 형식(feature, risk, additional_data, log_type, short_description, long_description, node_id)을 따릅니다. 데이터베이스 검증에는 강제 자동 거부 트리거가 없습니다. 두 가지 일치 결과 위험, 대체된 문서 위험, 해당 없음 위험은 구성 가능한 작업(DECLINE, REVIEW 또는 NO_ACTION)에 매핑됩니다. COULD_NOT_PERFORM_DATABASE_VALIDATION은 유일하게 고정된 동작으로, 기능을 항상 검토 중으로 라우팅합니다.

구성 가능한 위험

설정	위험 코드	동작
일치 없음 작업	`DATABASE_VALIDATION_NO_MATCH`	`REVIEW`(워크플로 기본값)는 해당 기능을 검토 중으로 설정합니다. `DECLINE`은 거부합니다. `NO_ACTION`은 상태에 영향을 주지 않고 경고를 기록합니다. 독립형 API의 `no_match_action` 파라미터는 기본값이 `DECLINE`입니다.
부분 일치 작업	`DATABASE_VALIDATION_PARTIAL_MATCH`	`NO_ACTION`(기본값)은 상태에 영향을 주지 않고 경고를 기록합니다. `REVIEW`는 해당 기능을 검토 중으로 설정합니다. `DECLINE`은 거부합니다.
일치 없음 작업	`DATABASE_VALIDATION_DOCUMENT_SUPERSEDED`	일치 없음 작업 설정을 공유하며 별도의 설정 항목은 없습니다. 등록기관의 정보가 제출된 내용과 모순되므로, 일치하지 않을 때 거부하는 조직은 오래된 자격 증명도 거부하게 됩니다.
해당 없음 작업	`DATABASE_VALIDATION_NOT_APPLICABLE`	`NO_ACTION`(기본값)은 상태에 영향을 주지 않고 경고를 기록합니다. `REVIEW`는 해당 기능을 검토 중으로 설정합니다. `DECLINE`은 거부합니다. 문서 자체를 전혀 확인할 수 없을 때(구성된 서비스가 조회하는 식별자가 없는 경우, 예: 주민등록번호가 없는 여권) 발생합니다.

구성된 작업은 경고의 log_type도 결정합니다: DECLINE → error, REVIEW → warning, NO_ACTION → information. 일치 결과 자체는 서비스별 validation 항목에서 종합됩니다(완전 일치가 하나라도 있는 경우 → full_match, 그 외 부분 일치가 있는 경우 → partial_match, 그 외 → no_match). 1×1 / 2×2 결과를 도출하는 전체 결정 로직은 매칭 방법을 참고하세요.

생성되는 경고

태그	간단한 설명	설명
`COULD_NOT_PERFORM_DATABASE_VALIDATION`	데이터베이스 검증을 수행할 수 없음	어떤 서비스도 사용 가능한 결과를 반환하지 않았습니다(`match_type`은 `null`로 유지됨). 일반적으로 필수 필드가 누락되었거나 형식이 잘못되었거나, 등록부에서 오류를 반환했기 때문입니다. `additional_data`에는 서비스별 건너뛰기 요약(`reason`, `database_validation_errors`, `missing_required_fields_by_service`, `invalid_format_fields_by_service`, `field_reasons_by_service`)이 포함되며, 독립형 API에서는 대신 `{ "validation_errors": [...] }`를 사용합니다. 이 경고가 발생해도 요금이 청구되지 않으며, 데이터가 수정될 때까지 해당 기능은 검토 중 상태로 이동합니다.
`DATABASE_VALIDATION_NOT_APPLICABLE`	이 문서에는 데이터베이스 검증을 적용할 수 없음	제공된 문서에 구성된 데이터베이스 서비스에서 요구하는 식별자가 포함되어 있지 않습니다(`match_type`은 `null`로 유지됨). 예를 들어 브라질 여권에는 CPF가 없으므로 CPF 등록부를 조회할 수 없습니다. 이는 해당 문서 유형에서 예상되는 동작이며 문서 자체의 문제를 나타내지는 않습니다. `additional_data`에는 서비스별 건너뛰기 요약이 포함됩니다. 이 경고가 발생해도 요금이 청구되지 않습니다. 작업은 구성 가능합니다(기본값 `NO_ACTION`).
`DATABASE_VALIDATION_PARTIAL_MATCH`	데이터베이스 검증 부분 일치	종합 `match_type`이 `partial_match`입니다. 검사된 일부 필드가 등록부와 일치하지만 전체가 일치하지는 않습니다. 작업은 구성 가능합니다(기본값 `NO_ACTION`).
`DATABASE_VALIDATION_NO_MATCH`	데이터베이스 검증 불일치	종합 `match_type`이 `no_match`입니다. 등록부에서 검사된 신원을 확인할 수 없습니다. 작업은 구성 가능합니다(워크플로에서는 기본값 `REVIEW`, 독립형 API에서는 `DECLINE`).
`DATABASE_VALIDATION_DOCUMENT_SUPERSEDED`	대체된 문서 버전	서비스가 `DOCUMENT_SUPERSEDED`를 반환했습니다. 등록부에서 해당 인물을 확인했으나, 제시된 문서의 버전이 기록된 것과 일치하지 않으며 그 이후 더 최신 버전이 발급되었습니다. 모든 개인 필드가 일치하여 `full_match`로 유지되는 `match_type`과 독립적으로 발생하며, 그렇지 않으면 이 결과를 감지할 수 없습니다. `additional_data`에 이를 보고한 서비스가 표시됩니다. No Match Action 설정을 따릅니다.

COULD_NOT_PERFORM_DATABASE_VALIDATION은 두 가지 서로 다른 상황을 다루며, 경고의 long_description(및 서비스별 실패의 경우 database_validation_errors[].message)에 단일 일반 문장 대신 둘 중 어느 상황이 적용되었는지가 명시됩니다. 즉, 서비스를 조회하기 전에 검사 데이터가 누락되었거나 형식이 잘못되었는지, 아니면 서비스를 조회했으나 사용 가능한 결과를 반환하지 않았는지 표시됩니다. 두 번째 경우, 등록부가 해당 시도에 대해 자체 진단 세부 정보를 보고한 경우 그 세부 정보가 메시지에 포함되므로 지원팀에 문의하지 않고도 원인을 파악할 수 있습니다. 업스트림 서비스의 이름은 응답에 포함되지 않습니다.

워크플로 세션에서 COULD_NOT_PERFORM_DATABASE_VALIDATION 또는 DATABASE_VALIDATION_NOT_APPLICABLE이 발생하면, 콘솔의 세션 상세 페이지에서 누락된 데이터를 입력했을 때 검사가 자동으로 다시 트리거됩니다. 필드를 저장하면 검증이 다시 실행되고, 성공하면 경고가 제거됩니다. 이는 해당 없음 작업으로 인해 세션이 거부된 경우에도 작동하므로, 데이터를 수정하여 거부된 세션을 바로잡을 수 있습니다. DATABASE_VALIDATION_NOT_APPLICABLE의 경우, 문서에 식별자가 포함될 수 있지만 인식되지 않은 경우(예: 국가 신분증 번호가 추출되지 않은 거주증) 재실행이 유용합니다. 식별자가 전혀 포함되지 않는 문서 유형(예: 국가 신분증 번호가 없는 여권)은 경고가 유지됩니다. 건너뛴 서비스에는 요금이 청구되지 않으며, 서비스가 청구 가능한 결과를 반환하는 경우에만 비용을 지불합니다.

예시

{
  "warnings": [
    {
      "feature": "DATABASE_VALIDATION",
      "risk": "DATABASE_VALIDATION_NO_MATCH",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Database validation no match",
      "long_description": "The system identified a no match in the database validation, requiring further investigation.",
      "node_id": "feature_db_validation_1"
    }
  ]
}

경고 유형

각 위험에는 애플리케이션 설정을 기반으로 심각도가 할당됩니다. 심각도는 세 가지 범주로 나뉩니다.

인증

인증

모니터링

플랫폼

데이터베이스 검증 경고 및 건너뛰기 코드

개요

구성 가능한 위험

생성되는 경고

예시

경고 유형

관련 항목

​개요

​구성 가능한 위험

​생성되는 경고

​예시

​경고 유형

​관련 항목

개요

구성 가능한 위험

생성되는 경고

예시

경고 유형

관련 항목