> ## 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 사용자 및 기업 엔티티의 상태와 전환 과정(생성, 인증, ACTIVE/FLAGGED/BLOCKED 전환, 삭제)을 설명합니다. 호출당 과금.

엔티티 라이프사이클은 Didit의 모든 사용자 및 기업 엔티티가 거치는 예측 가능한 과정입니다. 이 라이프사이클을 이해하면 온보딩, 지속적인 모니터링, 개선 조치 흐름을 설계하는 데 도움이 됩니다.

## 라이프사이클 다이어그램

```mermaid theme={null}
stateDiagram-v2
    [*] --> ACTIVE: Created (API, console, or auto from session)
    ACTIVE --> FLAGGED: Rule match / analyst review / suspicious pattern
    FLAGGED --> ACTIVE: Analyst clears / remediation completed
    ACTIVE --> BLOCKED: Manual block / blocklist match
    FLAGGED --> BLOCKED: Investigation concludes blocked
    BLOCKED --> ACTIVE: Manual unblock (analyst only)
```

## 상태 세부 정보

| 상태 | 의미 | 적용 방식 |
| - | - | - |
| `ACTIVE` | 기본값입니다. 엔티티가 정상 상태입니다. | 새 세션과 거래는 설정된 워크플로와 규칙에 따라 처리됩니다. |
| `FLAGGED` | 엔티티에 검토가 필요한 미해결 문제가 있습니다. | 새 세션은 계속 실행되지만 기본적으로 `IN_REVIEW`로 설정됩니다. 거래는 규칙에 따라 자동으로 상위 검토로 넘어갈 수 있습니다. |
| `BLOCKED` | 엔티티가 플랫폼에서 차단되었습니다. | 새 세션과 새 거래는 자동으로 거부됩니다. 이 `vendor_data`에 대해서는 새 세션 링크를 만들 수 없습니다. |

> [!NOTE]
>
> `PATCH /v3/users/{vendor_data}/update-status/` 또는 `PATCH /v3/businesses/{vendor_data}/update-status/`로 상태를 변경하면 webhook(`user.status.updated` / `business.status.updated`)이 발생하므로 하위 시스템이 실시간으로 대응할 수 있습니다.

## 라이프사이클 단계

**1. 생성**

엔티티는 다음 세 가지 방법 중 하나로 생성됩니다.

* 새 `vendor_data`로 세션을 시작하면 **자동 생성**됩니다. 엔티티는 `ACTIVE` 상태로 만들어집니다.
* `POST /v3/users/create/` 또는 `POST /v3/businesses/create/`를 사용해 **API로 사전 생성**됩니다. 상태 기본값은 `ACTIVE`입니다.
* 컴플라이언스 담당자가 **콘솔에서 생성**합니다. 담당자가 다르게 지정하지 않으면 상태는 `ACTIVE`로 시작합니다.

모든 엔티티에는 Didit이 생성한 `uuid`와 고객이 소유한 `vendor_data` 식별자가 부여됩니다.

**2. 인증**

세션은 `vendor_data`를 통해 엔티티에 연결됩니다. 각 세션은 설정된 [워크플로](https://docs.didit.me/ko/console/workflows.md)를 거치며, 여기에는 신분증 인증, 라이브니스 감지, 얼굴 대조, AML, 문서 확인, KYB의 경우 법인 등기부 조회 등이 포함됩니다.

완료된 세션은 엔티티의 누적 카운터를 업데이트합니다.

* `session_count`, `approved_count`, `declined_count`, `in_review_count`
* `features` 맵은 모든 세션에 걸쳐 각 기능의 최신 상태를 보여 줍니다(예: `{ "id_verification": "APPROVED", "aml": "IN_REVIEW" }`).
* 프로필 필드는 가장 최근에 승인된 세션에서 반영됩니다(예: `full_name`, `date_of_birth`, `portrait_image`).

**3. 활성 사용**

엔티티에 승인된 세션이 하나 이상 존재하면 다음 작업을 수행할 수 있습니다.

* 거래 페이로드에 `vendor_data`를 넣어 엔티티를 참조하는 **거래를 제출**합니다.
* **지속적인 AML 모니터링을 실행**합니다. 제재, PEP, 부정적 언론 보도 목록을 주기적으로 다시 검색합니다.
* **일정에 따라 재인증**합니다. 정해진 간격으로 같은 `vendor_data`에 대해 새 세션을 만듭니다.
* 세션과 거래 전반의 **위험 신호를 집계**합니다.

**4. 상태 전환**

엔티티 상태는 자동으로 또는 수동으로 변경됩니다.

**자동 전환**

* 거래가 검토 임계값을 넘거나 규칙이 엔티티를 감시 목록에 추가하면 `ACTIVE → FLAGGED`로 바뀝니다.
* 얼굴 생체 정보가 차단 목록 항목과 일치하면 `ACTIVE → BLOCKED`로 바뀝니다.

거부된 세션은 엔티티를 차단 목록에 자동으로 추가하지 않으므로 상태가 바뀌지 않습니다. 거부된 대상자를 차단하려면 수동으로 작업해야 합니다. [차단 목록 페이지](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`로 설정됩니다.

**수동 전환**은 분석가가 콘솔에서 상태를 변경하거나 `update-status` 엔드포인트를 호출할 때 발생합니다.

모든 전환은 `user.status.updated` 또는 `business.status.updated` webhook을 발생시킵니다.

**5. 삭제**

엔티티는 `POST /v3/users/delete/` 또는 `POST /v3/businesses/delete/`(일괄)로 삭제합니다. 엔티티 레코드는 영구적으로 제거됩니다. 사용자를 삭제하면 세션 삭제 후에도 보관되던 해당 사용자의 모든 [생체 인식 템플릿](https://docs.didit.me/ko/management-api/biometric-templates/overview.md)도 함께 삭제되므로, 해당 인물은 중복 감지와 얼굴 검색에서 더 이상 일치하지 않습니다.

인증 세션과 거래는 이 엔드포인트의 적용 대상이 아닙니다. 세션은 [세션 삭제](https://docs.didit.me/ko/sessions-api/delete-session.md) 또는 [세션 일괄 삭제](https://docs.didit.me/ko/management-api/sessions/batch-delete.md)로 삭제하고, 거래는 콘솔에서 삭제합니다.

## 활동 타임스탬프

엔티티는 활동을 추적하여 오래되었거나 활발한 프로필을 식별하는 데 도움을 줍니다.

| 타임스탬프 | 업데이트되는 시점 |
| - | - |
| `first_session_at` | 이 엔티티에 대해 첫 번째 세션이 생성되었을 때 |
| `last_session_at` | 가장 최근 세션이 생성되거나 업데이트되었을 때 |
| `last_activity_at` | 세션, 거래, 상태 변경, 프로필 업데이트 등 어떤 변경이라도 발생했을 때 |

휴면 엔티티를 필터링하거나, 재인증을 예약하거나, 지속적인 모니터링을 트리거하는 데 이 타임스탬프를 사용하십시오.

## 라이프사이클 중 발생하는 이벤트

| 라이프사이클 단계 | 발생하는 webhook |
| - | - |
| 생성(세션에서 자동 생성) | `status.updated`(세션), `user.data.updated` 또는 `business.data.updated` |
| 인증 | `status.updated`(세션), `data.updated` |
| 상태 변경 | `user.status.updated` 또는 `business.status.updated` |
| 거래 제출 | `transaction.created` |
| 거래 상태 변경 | `transaction.status.updated` |

페이로드 구조와 전송 방식은 [엔티티 webhook](https://docs.didit.me/ko/entities/webhooks.md)을 참조하십시오.

## 다음 단계

> [card] [vendor\_data 연결](https://docs.didit.me/ko/entities/vendor-data-linking.md)
>
> `vendor_data`가 세션, 거래, 엔티티를 어떻게 연결하는지 설명합니다.

> [card] [사용자 작업](https://docs.didit.me/ko/entities/users/operations.md)
>
> 사용자 엔티티를 생성, 업데이트, 상태 변경, 삭제하는 방법을 설명합니다.

> [card] [기업 작업](https://docs.didit.me/ko/entities/businesses/operations.md)
>
> 기업 엔티티를 생성, 업데이트, 상태 변경, 삭제하는 방법을 설명합니다.


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