> ## 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（精选）、股东或实际受益人，按国家/地区计费。

## 端点与计费

使用付费企业数据源的成功独立搜索，每次请求收取 **\$0.50**，与候选企业数量无关。空结果、失败的搜索，以及仅由其他数据源提供结果的搜索，均不收费。之后获取企业档案会单独计费。

检索分为三个数据等级，每个等级对应一个端点，价格按国家/地区设定（[各国家/地区价格](https://docs.didit.me/zh/getting-started/kyb-registry-pricing.md)）：

| 端点 | 获得的内容 | 价格 |
| - | - | - |
| [`POST /v3/kyb/search/`](https://docs.didit.me/zh/standalone-apis/kyb-registry-search) | 候选企业：名称、注册号、状态、类型 | 返回付费数据源结果时为 \$0.50 |
| [`POST /v3/kyb/select/`](https://docs.didit.me/zh/standalone-apis/kyb-registry-select) | **Lite**：企业档案（标识信息、状态、法律形式、成立日期、注册地址、经营业务、联系方式）以及高级管理人员 | Lite 价格：按国家/地区为 \$2.00-\$3.00 |
| [`POST /v3/kyb/shareholders/`](https://docs.didit.me/zh/standalone-apis/kyb-registry-shareholders) | Lite 的全部内容，外加直接股东及其股权比例区间 | 股东价格：按国家/地区为 \$5.00-\$22.00 |
| [`POST /v3/kyb/ubo/`](https://docs.didit.me/zh/standalone-apis/kyb-registry-ubo) | 股东的全部内容，外加通过股权链解析出的最终实际受益人 | UBO 价格：按国家/地区为 \$9.00-\$96.00 |

`select` 即 Lite 等级：托管式 KYB 工作流为 Lite 级别的登记检查计费时使用的正是它，其既有契约保持不变。欧洲指欧洲经济区（EEA）、英国和瑞士。

股东或 UBO 搜索会向提供该等级数据的股权结构数据源发起查询。当该数据源答复其不持有该企业时，搜索还会向该国家/地区的其他登记机构数据源发起查询，因此股权结构数据源未收录的企业仍会作为候选企业返回，而不会以人工录入告终。通过这种方式找到的候选企业保留您请求的等级：获取这些企业时会重新检查股权结构数据源；若其仍不持有该企业，则交付并计费 Lite 企业档案，且 `registry_ownership_status: "not_held"`。

> [!NOTE]
>
> **您为交付的等级付费。** 每个响应都包含 `registry_tier_requested` 和 `registry_tier_delivered`。当该国家/地区的登记机构不持有股权结构数据，或登记机构没有所选企业的股权记录时，股权结构请求将按可用的最高等级（通常为 Lite）交付并计费，`registry_ownership_status` 会说明原因。若解析后的报告未将任何自然人列为实际受益人，则该 UBO 请求按股东等级交付并计费。

> [!NOTE]
>
> **版本控制。** 股东和 UBO 端点仅存在于 `/v3/` 下。独立搜索费用同样适用于 `/v2/kyb/search/`；企业档案获取单独计费。

## 股权结构状态

`registry_ownership_status` 说明股东或 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` 或股东列表，并不能说明该企业的任何情况。

### 异步获取股权数据

部分登记机构需要按需查询：对于该来源从未查询过的企业，首次请求会在获取期间不返回股权部分，数据会在几分钟内到达。若将此情况报告为“无股权记录”，就会低估实际拥有股东的企业的股权情况，因此此时请求会返回 `pending`。

获取处于 `pending` 状态时，`fetch_status` 同样为 `pending`，响应状态为 `202 Accepted`。Didit 会自行重试该部分，无需您再次调用即可完成获取：

* 股权数据到达后，股东和实际受益人会出现在已保存的核验记录中，`registry_tier_delivered` 变为所交付的等级，并按该等级计费；
* 若在重试窗口结束时该部分仍为空，状态变为 `unavailable`，请求将按 Lite 交付和计费。

请保留 `request_id`，并轮询 `GET /v3/session/{request_id}/decision/`，直至 `registry_checks[0].company.fetch_status` 变为 `resolved`。在 `pending` 期间请勿重复发送获取请求：每次新的 `POST` 都是单独的请求，并分别计费。

使用 `POST /v3/kyb/search/` 查找候选企业。搜索不会创建已保存的核验记录。搜索的 `tier` 输入决定其查询的链路，参见[搜索等级](https://docs.didit.me/zh/standalone-apis/kyb-registry-search.md#搜索层级)。

登记机构搜索可能需要约 90 秒。若您希望 Didit 立即返回，并在候选企业准备就绪后通知您的 URL，请发送 `webhook_url`。搜索回调不带签名，这是有意设计的，因此您无需为这一轻量通知配置共享密钥。

使用 `POST /v3/kyb/select/`、`POST /v3/kyb/shareholders/` 或 `POST /v3/kyb/ubo/`，并附上返回的 `kyb_response_id`，即可获取所需等级的档案。获取会产生费用，并将结果作为 Manual Check 保存到 Business Console 中。

## 典型流程

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`，并使用它获取已保存的企业验证结果。

## 搜索回调

当服务提供方告知 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.