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

# 신원 인증 세션 API: KYC·KYB 통합 인증

> Didit의 통합 세션 API는 하나의 엔드포인트로 KYC와 KYB를 처리합니다. 사용량 기준 요금, 2초 미만 추론, 220+ 국가, 14,000+ 문서 지원, 월 $10 무료 크레딧을 제공합니다.

Didit에서 세션은 인증의 기본 단위입니다. 인증을 시작하면 **세션**이 생성되고, 인증이 끝나면 세션에 전체 decision payload가 담깁니다. 같은 세션 API로 두 종류를 모두 처리합니다:

| 종류 | 검증 대상 | Decision payload 포함 항목 |
| - | - | - |
| **사용자 인증(KYC) 세션** | 개인 | 신분증 인증, 라이브니스 감지, 얼굴 대조, 주소 증명(POA), NFC, 데이터베이스 검증, 전화번호, 이메일, AML, 설문지, 기기 및 IP 분석 |
| **기업 확인(KYB) 세션** | 회사 또는 법인 | 법인 등기부 확인, 주요 인물(임원/UBO), 문서 인증, 전화번호, 이메일, AML, 설문지, 기기 및 IP 분석 |

Academy 강의 중 사용자가 보게 되는 화면을 다루는 5:34 챕터에서는 호스팅 방식과 직접 화면을 구현하는 방식을 비교합니다. 이 API가 바로 그 선택을 대신 결정해 줍니다.

[호스팅 방식과 직접 화면 구현 비교 - Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=334\&rel=0\&playsinline=1)

## 종류는 워크플로에 따라 결정됩니다

[세션을 생성](https://docs.didit.me/ko/sessions-api/create-session.md)할 때 `workflow_id`를 전달합니다. 워크플로의 유형에 따라 세션이 사용자 인증인지 기업 확인인지가 결정되며, 호출하는 쪽에서 따로 선택하지 않습니다. KYB 워크플로는 기업 확인 세션을 만들고, KYC 워크플로는 사용자 인증 세션을 만듭니다.

## `session_kind` 판별자

세션 생성, 조회, 목록 조회, 상태 업데이트, 공유, 가져오기 등 모든 세션 응답에는 최상위 필드가 포함됩니다:

```json theme={null}
{
  "session_id": "...",
  "session_kind": "user",
  ...
}
```

* `"user"`: 이 세션은 **사용자 인증(KYC) 세션**입니다. 응답에 사용자 전용 기능 배열이 포함됩니다.
* `"business"`: 이 세션은 **기업 확인(KYB) 세션**입니다. 응답에 기업 전용 기능 배열이 포함됩니다.

이 필드를 사용해 클라이언트에서 응답 구조에 따라 처리를 분기하세요.

> [!NOTE]
>
> 열거형 값은 짧은 식별자인 `"user"`와 `"business"`입니다. API를 간결하게 사용할 수 있도록 값을 짧게 유지했습니다. 문서 전체에서는 명확성을 위해 \*\*사용자 인증(KYC)\*\*과 \*\*기업 확인(KYB)\*\*이라는 전체 명칭을 사용합니다.

## 종류별 기능 배열

결정 결과에 포함되는 기능 배열은 세션 종류에 따라 달라집니다. 한 종류에만 해당하는 필드는 해당 응답에 나타나지 않습니다(null 값이나 자리표시자는 없습니다):

| 기능 배열 | 사용자 인증(KYC) | 기업 확인(KYB) |
| - | :-: | :-: |
| `id_verifications` | ✅ | - |
| `liveness_checks` | ✅ | - |
| `face_matches` | ✅ | - |
| `nfc_verifications` | ✅ | - |
| `poa_verifications` | ✅ | - |
| `database_validations` | ✅ | - |
| `registry_checks` | - | ✅ |
| `document_verifications` | - | ✅ |
| `key_people_checks` | - | ✅ |
| `aml_screenings` | ✅ | ✅ |
| `phone_verifications` | ✅ | ✅ |
| `email_verifications` | ✅ | ✅ |
| `questionnaire_responses` | ✅ | ✅ |
| `ip_analyses` | ✅ | ✅ |
| `reviews` | ✅ | ✅ |
| `contact_details` | ✅ | ✅ |

## 공통 최상위 필드

모든 세션(두 종류 모두)에는 다음 필드가 포함됩니다:

| 필드 | 설명 |
| - | - |
| `session_id` | 세션의 UUID |
| `session_kind` | `"user"`(사용자 인증/KYC) 또는 `"business"`(기업 확인/KYB) |
| `session_number` | 애플리케이션 내의 순차 번호 |
| `session_url` | 호스팅 인증 URL |
| `status` | 세션 전체 상태: `APPROVED`, `DECLINED`, `IN_REVIEW`, `IN_PROGRESS` 등 |
| `workflow_id` | 사용된 워크플로의 UUID |
| `vendor_data` | 해당 개체를 식별하기 위한 귀사의 식별자. [자세히 보기](https://docs.didit.me/ko/entities/vendor-data-linking.md) |
| `metadata` | 생성 시 첨부한 자유 형식 JSON |
| `callback` | 선택 사항인 콜백 URL |
| `features` | 워크플로가 실행하는 기능의 쉼표 구분 목록 |
| `expected_details` | 교차 검증을 위한 선택 사항인 예상 데이터 payload |
| `created_at`, `expires_at` | 타임스탬프 |

## 지원되는 endpoint

아래 endpoint는 두 종류를 모두 지원합니다. 별도의 `/v3/business-session/*` 경로는 없습니다.

| Endpoint | 지원 대상 |
| - | - |
| [`POST /v3/session/`](https://docs.didit.me/ko/sessions-api/create-session) | 워크플로 유형에 따라 사용자 인증 세션 또는 기업 확인 세션을 생성합니다 |
| [`GET /v3/session/{id}/decision/`](https://docs.didit.me/ko/sessions-api/retrieve-session) | 두 종류 모두 조회합니다. `session_id`를 기준으로 분기합니다 |
| [`GET /v3/sessions/`](https://docs.didit.me/ko/sessions-api/list-sessions) | 두 종류 모두 목록으로 조회합니다. `session_kind` 쿼리 파라미터로 필터링할 수 있습니다 |
| [`PATCH /v3/session/{id}/update-status/`](https://docs.didit.me/ko/sessions-api/update-status) | 두 종류 모두 업데이트합니다 |
| [`DELETE /v3/session/{id}/delete/`](https://docs.didit.me/ko/sessions-api/delete-session) | 두 종류 모두 삭제합니다 |
| [`GET /v3/session/{id}/generate-pdf/`](https://docs.didit.me/ko/sessions-api/generate-pdf) | 두 종류 모두 PDF를 생성합니다. 사용자 인증 또는 기업 확인 템플릿으로 연결됩니다 |
| [`POST /v3/session/{id}/share/`](https://docs.didit.me/ko/sessions-api/share-session/share) | 공유 토큰에 `session_kind`가 포함됩니다 |
| [`POST /v3/session/import-shared/`](https://docs.didit.me/ko/sessions-api/share-session/import) | 두 종류 모두 가져옵니다. 토큰의 `session_kind`를 그대로 유지합니다 |

## 조회 방식

사용자 인증 세션과 기업 확인 세션은 서로 다른 두 종류입니다. ID는 UUID이므로 충돌이 발생하지 않습니다. `session_id`로 endpoint를 호출하면 Didit은 다음 순서로 처리합니다:

1. 사용자 인증 테이블에서 ID를 먼저 찾습니다(대부분의 트래픽이 여기에 해당합니다).
2. 찾지 못하면 기업 확인 테이블에서 찾습니다.
3. 두 테이블 모두에 일치하는 항목이 없으면 404를 반환합니다.

API에 어떤 종류를 찾는지 알려 줄 필요는 없습니다.

## 상태 값은 동일합니다

상태 값은 두 종류에서 동일하며, API는 여기에 적힌 그대로 값을 반환합니다: `"Not Started"`, `"In Progress"`, `"Approved"`, `"Declined"`, `"In Review"`, `"Abandoned"`, `"Expired"`, `"Kyc Expired"`, `"Resubmitted"`, `"Awaiting User"`. 값 비교는 정확히 일치해야 하며 대소문자를 구분합니다. 전체 목록은 [인증 상태](https://docs.didit.me/ko/integration/verification-statuses.md)를 참고하세요.

## webhook

webhook 이벤트에는 이미 `session_kind` 필드가 포함되어 있으므로, webhook 핸들러에서 종류별로 분기할 수 있습니다.

| 이벤트 | 종류 | 발생 시점 |
| - | - | - |
| `status.updated` | 둘 다 | 세션의 상태가 변경되었을 때. 페이로드에는 `session_kind: "user"` 또는 `"business"`가 포함됩니다. |
| `data.updated` | 둘 다 | 세션의 데이터가 변경되었을 때(기능 결과, 등기부 갱신, 지속적인 AML 모니터링). 페이로드에 `session_kind`가 포함됩니다. |
| `business.status.updated` / `business.data.updated` | 기업 엔티티 | 연결된 기업 엔티티가 변경되었을 때. |
| `user.status.updated` / `user.data.updated` | 사용자 엔티티 | 연결된 사용자 엔티티가 변경되었을 때. |

서명 검증과 재시도 동작은 [webhook](https://docs.didit.me/ko/integration/webhooks.md) 문서를, 기업 확인(KYB) 이벤트 카탈로그는 [KYB webhook](https://docs.didit.me/ko/business-verification/webhooks.md) 문서를 참고하세요.

## 다음 단계

> [card] [세션 생성](https://docs.didit.me/ko/sessions-api/create-session.md)
>
> 사용자 인증 또는 기업 확인(KYB)을 시작합니다.

> [card] [세션 조회](https://docs.didit.me/ko/sessions-api/retrieve-session.md)
>
> 결정 결과를 가져옵니다. 두 종류 모두 지원합니다.

> [card] [세션 목록](https://docs.didit.me/ko/sessions-api/list-sessions.md)
>
> `session_kind`로 필터링합니다.

> [card] [상태 업데이트](https://docs.didit.me/ko/sessions-api/update-status.md)
>
> 승인, 거부, 검토, 재제출을 처리합니다.

> [card] [PDF 생성](https://docs.didit.me/ko/sessions-api/generate-pdf.md)
>
> 종류별 PDF 보고서를 생성합니다.

> [card] [공유 및 가져오기](https://docs.didit.me/ko/sessions-api/share-session/overview.md)
>
> 앱 간에 세션을 옮깁니다.


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