> ## 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이 User 엔티티에 차단을 적용하는 방식, 식별자 유형, 차단 확인 방법, 항목 추가 및 삭제 방법을 설명합니다.

차단 목록은 컴플라이언스 검사에 실패한 사용자가 새 세션을 만들거나 새 거래를 실행하지 못하도록 합니다. Didit은 **식별자 유형**별로 차단 목록을 지원하므로, 같은 악성 행위자를 여러 데이터 지점(얼굴, 문서, 이메일, 전화번호, 사용자 vendor\_data)에서 한꺼번에 차단할 수 있습니다.

## 사용자에게 지원되는 식별자 유형

| 유형 | 키 | 일치 조건 |
| - | - | - |
| 얼굴 | `FACE` | 새 세션의 라이브니스 셀피가 차단된 얼굴과 일치하는 경우 |
| 문서 번호 | `DOCUMENT` | 새 신분증 제출의 문서 번호가 차단된 문서 번호와 일치하는 경우 |
| 이메일 | `EMAIL` | 새 세션이나 거래가 차단된 이메일을 사용하는 경우 |
| 전화번호 | `PHONE` | 새 세션이나 거래가 차단된 전화번호를 사용하는 경우 |
| 주소 | `IP_ADDRESS` | 제출자의 IP가 일치하는 경우. 단일 IP(`1.2.3.4`)와 CIDR 범위(`10.0.0.0/8`)를 지원합니다 |
| 기기 지문 | `DEVICE_FINGERPRINT` | 제출자의 기기 지문이 일치하는 경우 |
| 사용자 | `USER` | 세션이나 거래가 차단된 `vendor_data`를 사용하는 경우 |

각 식별자 유형은 자연스러운 접점에서 적용됩니다.

* 얼굴과 문서: 새 세션 중에 적용됩니다.
* 이메일과 전화번호: 이를 수집하는 세션 단계 중이나 거래 페이로드에서 적용됩니다.
* IP와 기기: 세션 중 기기 및 IP 분석 단계에서 적용됩니다.
* 사용자 vendor\_data: 세션 또는 거래 생성 시 적용됩니다.

## 차단 목록에 추가되는 방식

> [!NOTE]
>
> 거부된 세션은 어떤 사용자도 차단 목록에 추가하지 않습니다. 세션은 `Declined` 상태로 끝나고, 사용자는 `ACTIVE` 상태를 유지하며, 목록 항목도 기록되지 않으므로 같은 사람이 다른 세션을 시작할 수 있습니다. 차단 목록 추가는 수동 작업입니다. [Blocklist page](https://docs.didit.me/ko/console/blocklist-users.md)에서 항목을 추가하거나 [Lists API](https://docs.didit.me/ko/management-api/lists/overview.md)를 사용하세요. `USER` 항목(사용자의 `vendor_data`)을 추가하면 사용자 상태도 `BLOCKED`로 바뀝니다.

**1. 자동: 차단 목록 일치 시**

들어온 세션이 기존 차단 목록 항목과 일치하면, 세션은 `blocked_face`, `blocked_document`, `blocked_email` 등과 같은 사유 코드와 함께 자동으로 거부됩니다.

**2. 수동: 콘솔에서**

분석가는 *Users → \[user] → Actions → Add to blocklist*에서 사용자를 차단하고, 차단 목록에 포함할 식별자를 하나 이상 선택합니다.

**3. 프로그래밍 방식: Lists API 사용**

[Lists API](https://docs.didit.me/ko/management-api/lists/overview.md)를 사용해 프로그래밍 방식으로 항목을 추가하세요. 이는 콘솔이 내부적으로 사용하는 것과 같은 API입니다.

## 시스템 목록과 사용자 지정 목록

모든 애플리케이션에는 식별자 유형마다 하나씩 있는 **시스템 차단 목록**이 있으며, Didit이 자동으로 관리합니다. 이름을 바꾸거나 삭제할 수 없습니다. 사용자 지정 목록은 직접 만들고, 이름을 붙이고, 범위를 정할 수 있습니다.

| 목록 | 생성 주체 | 설명 |
| - | - | - |
| System Face Blocklist | Didit | 애플리케이션의 기준 얼굴 차단 목록 |
| System Document Blocklist | Didit | 기준 문서 번호 차단 목록 |
| System Email Blocklist | Didit | 기준 이메일 차단 목록 |
| System Phone Blocklist | Didit | 기준 전화번호 차단 목록 |
| System User Blocklist | Didit | 차단된 `vendor_data` 식별자 |
| Custom blocklists | 사용자 | 지역, 파트너, 위험 등급별 등 범위가 지정된 목록 |

## Lists API로 사용자를 차단 목록에 추가하기

[Lists API](https://docs.didit.me/ko/management-api/lists/overview.md)를 사용해 차단 목록 항목을 추가하세요. `vendor_data`로 사용자를 차단하려면 해당 차단 목록에 USER 유형 항목을 추가합니다.

1. `entry_type=user`와 `is_system=true`로 필터링해 [모든 목록 조회](https://docs.didit.me/ko/management-api/lists/list.md)를 실행하여 시스템 사용자 차단 목록을 찾습니다.
2. 해당 목록에 `value`를 사용자의 `vendor_data`로 설정해 [항목 생성](https://docs.didit.me/ko/management-api/lists/create-entry.md)을 실행합니다.

얼굴로 사용자를 차단하려면 [Faces & biometrics](https://docs.didit.me/ko/entities/users/faces-and-biometrics.md#차단-목록에-얼굴-업로드)를 참고하세요. 이메일, 전화번호, 문서 또는 IP로 차단하려면 해당 시스템 차단 목록을 사용하고 `value`에 적절한 식별자를 입력합니다.

## 적용 흐름

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Didit
    participant Lists as Blocklist check
    participant Workflow
    Client->>Didit: POST /v3/session/ (vendor_data=user-42)
    Didit->>Lists: Does user-42 match a USER blocklist?
    Lists-->>Didit: Match found
    Didit-->>Client: Session auto-declined (reason: blocked_user)
```

얼굴과 문서 차단 목록의 경우, 검사는 인증 단계에서 이루어집니다.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Didit
    participant Lists as Face Blocklist
    User->>Didit: Liveness capture
    Didit->>Lists: Embedding search
    Lists-->>Didit: Match similarity > threshold
    Didit-->>User: Session declined (reason: blocked_face)
```

## 차단 목록에서 제거하기

* **콘솔**: *Blocklist → \[type] → row actions → Remove*.
* **API**: 목록 UUID와 항목 UUID를 사용하여 [항목 삭제](https://docs.didit.me/ko/management-api/lists/delete-entry.md) 엔드포인트를 호출합니다.

항목을 제거해도 사용자 상태가 자동으로 `ACTIVE`로 돌아가지는 않습니다. 새 세션을 허용하려면 `PATCH /v3/users/{vendor_data}/update-status/`를 사용해 상태를 변경하세요.

## 차단 목록 감사 추적

차단 목록에 대한 모든 추가 및 제거는 [감사 로그](https://docs.didit.me/ko/console/audit-logs.md)에 기록됩니다.

* 항목을 추가한 주체(사용자 이메일 또는 `'system'`, `'api'`).
* 추가하거나 제거한 시각.
* 사유를 설명하는 선택적 `comment`.
* 항목이 자동으로 생성된 경우 연결된 세션 또는 거래.

## 다음 단계

> [card] [Lists API](https://docs.didit.me/ko/management-api/lists/overview.md)
>
> 차단 목록 및 허용 목록 API 전체 참조.

> [card] [콘솔 차단 목록](https://docs.didit.me/ko/console/blocklist-users.md)
>
> UI에서 차단 목록을 관리합니다.

> [card] [Faces & biometrics](https://docs.didit.me/ko/entities/users/faces-and-biometrics.md)
>
> 얼굴 차단 목록의 작동 방식.


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