> ## 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 레지스트리 API: 기업 검색 및 선택

> Didit의 KYB 레지스트리 API로 법인 등기부를 검색하고, 필요한 등급(Lite(select), 주주 또는 실소유자(UBO))으로 기업 정보를 조회하세요. 요금은 국가별로 책정됩니다.

## 엔드포인트 및 요금

유료 기업 데이터 소스를 사용한 독립형 검색이 성공하면 후보 수와 관계없이 **요청당 \$0.50**이 청구됩니다. 결과가 없는 검색, 실패한 검색, 다른 소스의 결과만 반환된 검색은 청구되지 않습니다. 이후 프로필을 조회하면 별도로 청구됩니다.

조회는 세 가지 데이터 등급으로 제공되며, 등급마다 엔드포인트가 하나씩 있고 가격은 국가별로 책정됩니다([국가별 가격](https://docs.didit.me/ko/getting-started/kyb-registry-pricing.md)).

| 엔드포인트 | 제공되는 정보 | 가격 |
| - | - | - |
| [`POST /v3/kyb/search/`](https://docs.didit.me/ko/standalone-apis/kyb-registry-search) | 후보 기업: 명칭, 등록번호, 상태, 유형 | 유료 소스 결과가 반환될 때 \$0.50 |
| [`POST /v3/kyb/select/`](https://docs.didit.me/ko/standalone-apis/kyb-registry-select) | **Lite**: 기업 프로필(식별자, 상태, 법적 형태, 설립일, 등록 주소, 사업 활동, 연락처 정보)과 임원 정보 | Lite 가격: 국가에 따라 \$2.00-\$3.00 |
| [`POST /v3/kyb/shareholders/`](https://docs.didit.me/ko/standalone-apis/kyb-registry-shareholders) | Lite 정보에 더해 지분 구간이 포함된 직접 주주 정보 | 주주 가격: 국가에 따라 \$5.00-\$22.00 |
| [`POST /v3/kyb/ubo/`](https://docs.didit.me/ko/standalone-apis/kyb-registry-ubo) | 주주 정보에 더해 소유 구조를 거쳐 확인된 최종 실소유자 정보 | UBO 가격: 국가에 따라 \$9.00-\$96.00 |

`select`는 Lite 등급입니다. 호스팅 KYB 워크플로에서 Lite 수준의 등기부 확인에 대해 청구되는 항목이며, 기존 계약 구조를 그대로 유지합니다. 유럽은 EEA, 영국, 스위스를 의미합니다.

Shareholders 또는 UBO 검색은 해당 등급을 제공하는 소유 구조 데이터 소스를 조회합니다. 이 소스가 해당 기업을 보유하지 않는다고 응답하면, 검색은 해당 국가의 다른 등기부 소스에도 조회합니다. 따라서 소유 구조 데이터 소스에 없는 기업도 후보로 제시되며, 수동 입력으로 끝나지 않습니다. 이 경로로 찾은 후보도 요청한 등급을 유지합니다. 조회 시 소유 구조 데이터 소스를 다시 확인하며, 여전히 해당 기업을 보유하지 않으면 Lite 프로필이 전달되고 그 등급으로 청구됩니다. 이때 `registry_ownership_status: "not_held"`가 반환됩니다.

> [!NOTE]
>
> **전달된 등급에 대해 요금이 청구됩니다.** 모든 응답에는 `registry_tier_requested`와 `registry_tier_delivered`가 포함됩니다. 해당 국가의 등기부에 소유 구조 데이터가 없거나, 선택한 기업에 대해 등기부에 소유 구조 기록이 없으면, 소유 구조 요청은 이용 가능한 최고 등급(보통 Lite)으로 전달되고 그 등급으로 청구됩니다. 이때 `registry_ownership_status`에 그 이유가 표시됩니다. UBO 요청의 조회 결과에 실소유자로 지정된 자연인이 없으면 Shareholders 등급으로 전달되고 청구됩니다.

> [!NOTE]
>
> **버전 관리.** Shareholders 및 UBO 엔드포인트는 `/v3/`에서만 제공됩니다. 독립형 검색 요금은 `/v2/kyb/search/`에도 적용됩니다. 프로필 조회는 별도로 청구됩니다.

## 소유 구조 상태

`registry_ownership_status`는 Shareholders 또는 UBO 요청에서 소유 구조 부분에 어떤 일이 일어났는지를 나타냅니다.

| 값 | 의미 |
| - | - |
| `not_requested` | Lite 조회 요청이었으므로 소유 구조는 요청되지 않았습니다. |
| `delivered` | 등기부가 소유 구조 데이터를 제공했으며, `registry_tier_delivered`의 등급이 과금되는 등급입니다. |
| `not_held` | 소유권 등기부가 응답했지만 이 회사를 목록에 포함하지 않으므로 제공할 소유 구조 기록이 없습니다. 회사는 해당 국가의 다른 등기부 출처에서 확인되었습니다. 대신 Lite 프로필이 제공되고 과금되며, `registry_data.ownership_error: "company_not_found"`가 설정됩니다. |
| `unavailable` | 그 밖의 이유로 소유 구조 데이터가 제공되지 않았습니다. 등기부가 보유한 기록에 소유자가 없거나, 등기부가 소유 구조 섹션을 아예 반환하지 않았거나, 조회할 수 없었던 경우입니다. 어떤 경우인지는 `registry_data.ownership_error`에 표시됩니다. 대신 Lite 프로필이 제공되고 과금됩니다. |
| `pending` | 소유 구조 섹션이 아직 등기부에서 조회되지 않았습니다. 조회가 끝나기 전까지는 과금되지 않으며, 그동안 `registry_tier_delivered`는 `null`입니다. |

`not_held`와 `unavailable`은 모두 Lite로 제공되고 과금되지만, 같은 결과가 아닙니다. `not_held`는 소유 정보 출처가 회사를 다루지 않는다는 뜻으로, 즉 적용 범위의 공백을 의미합니다. 반면 `unavailable`은 데이터가 제공되지 않았다는 뜻으로, 장애이거나 등기부가 비워 둔 섹션을 뜻합니다. `registry_data.ownership_error`에 그 이유가 나타납니다. 이전에는 소유권 등기부가 회사를 목록에 포함하지 않아 `unavailable`로 보고되던 선택 건이 이제 `not_held`로 보고됩니다. 상태에 따라 분기 처리한다면 두 상태를 모두 같은 Lite 제공으로 취급하십시오. 다음 두 값은 서로 다른 결과를 의미하므로 같은 것으로 읽으면 안 됩니다.

| `ownership_error` | 의미 |
| - | - |
| `no_owners_on_record` | 등기부가 소유 구조 섹션에 응답했고 소유자가 없다고 명시했습니다. 해당 등기부에 이 회사의 지분 구조표가 없습니다. |
| `ownership_section_unavailable` | 등기부가 소유 구조 섹션을 반환하지 않았으므로 이 섹션에 대해 아무것도 제공되지 않았습니다. 목록이 비어 있는 것이 아니라 누락된 것이므로, 누가 회사를 소유하는지에 대해서는 아무 정보도 주지 않습니다. |

등기부가 반환하지 않은 섹션은 `registry_data.section_errors`에 구조화된 형태로도 기록되며, 키는 섹션(`officers`, `shareholders`, `group_structure`)이고 값은 등기부가 응답한 상태입니다.

```json theme={null}
{
  "section_errors": {
    "shareholders": {
      "status_code": 404
    }
  }
}
```

`section_errors`는 발생 경위가 아니라 현재 보유한 응답을 설명합니다. 첫 요청에서 반환되지 않았다가 이후 조회(아래 비동기 조회 참조)에서 제공된 섹션은 항목이 사라지므로, `registry_ownership_status`, `ownership_error`, `section_errors`는 항상 일치합니다. `delivered` 섹션에는 항목이 절대 없으며, `no_owners_on_record`인 경우에는 `shareholders`에 대한 항목도 없습니다. 또한 섹션이 일부만 제공되는 일은 없습니다. 등기부가 목록의 첫 페이지는 제공했지만 이후 페이지 제공에 실패하면 그 조회는 해당 시도에서 완료되지 않은 것으로 처리됩니다. `pending` 상태의 조회는 다음 주기에 재시도되며, 새 요청은 등기부 사용 불가 오류로 응답합니다. 따라서 제공된 `officers` 또는 주주 목록은 항상 등기부가 보유한 전체 목록입니다. `section_errors`에 나열된 섹션은 결과가 비어 있는 것이 아니라 아예 제공되지 않은 데이터로 취급하십시오. `section_errors` 항목이 있는 상태에서 `officers` 또는 주주 목록이 비어 있다면, 그 사실은 회사에 대해 아무것도 말해 주지 않습니다.

### 비동기로 조회되는 소유 구조

일부 등기부는 요청이 있을 때 조회됩니다. 출처에 한 번도 조회된 적 없는 회사에 대해 처음 요청하면, 데이터를 가져오는 동안 소유 구조 섹션 없이 응답이 반환되며, 데이터는 약 2분 안에 도착합니다. 이 상황을 "등록된 소유자 없음"으로 보고하면 실제로 주주가 있는 회사의 소유 구조를 과소평가하게 되므로, 대신 요청은 `pending` 상태로 반환됩니다.

조회가 `pending`인 동안 `fetch_status`도 `pending`이며, 응답 상태는 `202 Accepted`입니다. Didit가 해당 섹션을 자동으로 재시도하여 추가 호출 없이 조회를 완료합니다.

* 소유 구조 데이터가 도착하면 주주와 실소유자가 저장된 확인 건에 나타나고, `registry_tier_delivered`는 제공된 등급이 되며, 사용량은 그 등급으로 과금됩니다.
* 재시도 기간이 끝났을 때 섹션이 여전히 비어 있으면 상태는 `unavailable`이 되고, 요청은 Lite로 제공되고 과금됩니다.

요청 시 받은 `request_id`를 보관하고, `registry_checks[0].company.fetch_status`가 `resolved`가 될 때까지 `GET /v3/session/{request_id}/decision/`을 폴링하십시오. `pending` 상태인 동안에는 조회 요청을 다시 보내지 마십시오. 모든 새 `POST`는 별도의 과금 대상 요청입니다.

`POST /v3/kyb/search/`를 사용하여 후보 회사를 찾으십시오. 검색은 저장된 확인 건을 만들지 않습니다. 검색 `tier` 입력값은 검색할 체인을 결정합니다. 자세한 내용은 [검색 등급](https://docs.didit.me/ko/standalone-apis/kyb-registry-search.md#검색-등급)을 참조하십시오.

등기부 검색은 약 90초가 걸릴 수 있습니다. 즉시 응답을 받고 후보가 준비되면 URL로 알림을 받고 싶다면 `webhook_url`을 보내십시오. 검색 콜백은 의도적으로 서명되지 않으므로, 이 가벼운 알림을 위해 공유 비밀을 설정할 필요가 없습니다.

반환된 `kyb_response_id`와 함께 `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` 또는 `POST /v3/kyb/ubo/`를 사용하여 필요한 등급의 프로필을 조회하십시오. 조회에는 과금이 발생하며, 결과는 Business Console에 Manual Check로 저장됩니다.

## 일반적인 흐름

1. 원하는 `tier`로 회사명, 등록번호, 국가를 기준으로 검색하십시오(`basic`이 기본 Lite 체인이며, `shareholders`와 `ubo`는 해당 등급의 체인을 검색합니다).
2. `search_resolved=false`이면 폴링하지 말고 선택 사항인 `webhook_url` 콜백을 기다리십시오.
3. 반환된 후보를 운영자 또는 고객에게 보여 주십시오.
4. 필요한 등급으로 일치하는 `kyb_response_id`를 조회하십시오(Lite는 select, 주주는 shareholders, UBO는 ubo를 사용합니다).
5. 반환된 `request_id`를 저장하고, 이를 사용하여 저장된 기업 확인(KYB) 결과를 조회하십시오.

## 검색 콜백

제공자가 검색이 완료되었다고 Didit에 알리면, Didit은 `webhook_url`로 `POST` 요청을 한 번 보냅니다:

```json theme={null}
{
  "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "metadata": {
    "source": "onboarding"
  },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": {
    "companies": [
      {
        "kyb_response_id": "kyb_resp_123",
        "name": "TESCO PLC",
        "registration_number": "00445790",
        "status": "active",
        "type": "Public Limited Company",
        "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA",
        "risk_level": null,
        "fetch_status": "pending"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "timestamp": 1767225600,
  "created_at": 1767225600
}
```

이 콜백은 전달 알림으로 취급하십시오. 반환된 `kyb_response_id`를 `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` 또는 `POST /v3/kyb/ubo/`와 함께 사용하여 과금 대상인 등기 프로필 조회를 실행하십시오.


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