> ## 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 기업 엔티티 모델 안내: 법인 등기 데이터, 실소유자, 임원, AML 상태, 문서, KYB 세션 집계, 연결된 거래를 포함합니다. 폐쇄형 KYB.

이 페이지는 기업(Business) 엔티티의 모든 필드와 Didit이 각 필드를 채우는 방식을 설명합니다.

## 신원 필드

| 필드 | 타입 | 설명 |
| - | - | - |
| `uuid` | UUID | Didit이 할당한 기본 키입니다. 안정적이며 고유합니다. |
| `didit_internal_id` | string | 사람이 읽을 수 있는 내부 식별자입니다. |
| `vendor_data` | string | 귀사가 해당 기업을 식별하는 값입니다. 애플리케이션마다 고유합니다. [자세히 보기](https://docs.didit.me/ko/entities/vendor-data-linking.md). |
| `display_name` | string | 콘솔에 표시되는 이름을 재정의합니다. 기본값은 `legal_name` 또는 `vendor_data`입니다. |
| `legal_name` | string | 등록된 법인의 정식 명칭입니다. 가장 최근에 승인된 기업 확인(KYB) 세션의 법인 등기부 조회 결과에서 전파됩니다. |
| `registration_number` | string | 공식 법인 등록번호입니다. 법인 등기부에서 전파됩니다. |
| `country_code` | string (ISO 3166-1 alpha-3) | 설립 국가입니다. |

> [!NOTE]
>
> `legal_name`, `registration_number`, `country_code`는 검증된 법인 등기부 조회에서 파생된 경우 읽기 전용입니다. 콘솔에서 수동으로 재정의하거나 `PATCH /v3/businesses/{vendor_data}/`를 통해 재정의할 수 있지만, 재정의 내역은 감사 로그에 표시됩니다.

## 상태

| 필드 | 타입 | 값 | 설명 |
| - | - | - | - |
| `status` | enum | `ACTIVE`, `FLAGGED`, `BLOCKED` | 향후 세션과 거래에 대한 집행을 제어합니다. [수명 주기](https://docs.didit.me/ko/entities/lifecycle.md)를 참조하십시오. |

## 세션 집계 필드

| 필드 | 타입 | 설명 |
| - | - | - |
| `session_count` | int | 이 기업에 대해 생성된 기업 확인(KYB) 세션의 총 개수입니다. |
| `approved_count` | int | `Approved`로 완료된 세션 수입니다. |
| `declined_count` | int | `Declined`로 완료된 세션 수입니다. |
| `in_review_count` | int | 현재 `In Review` 상태인 세션 수입니다. |
| `features` | object | `KYB` 키 아래에 있는 최신 기업 인증 상태입니다. |

### `features` 맵

```json theme={null}
{
  "KYB": "Approved"
}
```

이 맵에는 `KYB` 키 하나가 있으며, 기업의 최신 인증 상태를 담습니다. 값은 `"Not Finished"`, `"Approved"`, `"Declined"`, `"In Review"`, `"Resub Requested"` 중 하나입니다.
개별 KYB 기능의 상태는 세션 결정을 확인하십시오.

모든 세션을 순회하지 않고 기업이 현재 완전히 인증되었는지 빠르게 확인하려면 `features` 맵을 사용하십시오.

## 활동 타임스탬프

| 필드 | 타입 | 업데이트 시점 |
| - | - | - |
| `first_session_at` | ISO timestamp | 첫 번째 기업 확인(KYB) 세션이 생성되었을 때 |
| `last_session_at` | ISO timestamp | 가장 최근 세션이 생성되거나 업데이트되었을 때 |
| `last_activity_at` | ISO timestamp | 세션, 거래, 상태, 프로필, 메모 등 모든 변경 시 |
| `created_at` | ISO timestamp | 엔티티 행이 생성되었을 때 |
| `updated_at` | ISO timestamp | 엔티티 행이 마지막으로 업데이트되었을 때 |

## 메타데이터

| 필드 | 타입 | 설명 |
| - | - | - |
| `metadata` | object (JSON) | 귀사가 제어하는 자유 형식 JSON입니다. |
| `tags[]` | array | 콘솔 또는 API에서 관리하는 태그입니다. |

## 관계(기업 행에 저장되지 않음)

| 관계 | 접근 방법 |
| - | - |
| 기업 확인(KYB) 세션 | `GET /v3/sessions?vendor_data=<value>` |
| 연결된 사용자(임원, UBO, 이사) | 콘솔의 기업 상세 페이지에 표시됩니다. 가장 최근에 승인된 기업 확인(KYB) 세션에서 파생됩니다. |
| 거래(신청자 또는 거래 상대방으로서) | 기업의 `vendor_data`로 거래를 필터링하십시오. |
| 문서 | 기업 확인(KYB) 세션 결정을 통해 확인하십시오. |
| AML 일치 항목 | 기업 확인(KYB) 세션 결정을 통해 확인하십시오. |

## 응답 예시

```json theme={null}
{
  "uuid": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "didit_internal_id": "B-2026-00018",
  "vendor_data": "biz-acme",
  "display_name": "Acme Corp",
  "legal_name": "Acme Corporation Limited",
  "registration_number": "12345678",
  "country_code": "GBR",
  "status": "ACTIVE",
  "session_count": 2,
  "approved_count": 1,
  "declined_count": 0,
  "in_review_count": 1,
  "features": {
    "KYB": "Approved"
  },
  "first_session_at": "2025-09-01T12:00:00Z",
  "last_session_at": "2026-04-01T09:00:00Z",
  "last_activity_at": "2026-04-16T10:00:00Z",
  "metadata": { "partner": "Acme Holdings" }
}
```

## 다음 단계

> [card] [작업](https://docs.didit.me/ko/entities/businesses/operations.md)
>
> 생성, 업데이트, 상태 변경, 삭제를 수행합니다.

> [card] [KYB 이력](https://docs.didit.me/ko/entities/businesses/kyb-history.md)
>
> 기업과 연결된 모든 세션을 조회합니다.

> [card] [API 레퍼런스](https://docs.didit.me/ko/management-api/businesses/get.md)
>
> GET /v3/businesses/{vendor_data}/ 스키마입니다.


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