KYB 集成指南：架构与模式（Didit）

本指南是快速入门的配套文档，涵盖架构、每项集成决策，以及确保 KYB 在生产环境中稳定运行的运维模式。

架构

身份验证

所有请求都需要在 x-api-key 请求头中传入应用的 API 密钥。有关密钥轮换、环境隔离和权限范围，请参阅 API 身份验证。

创建会话

唯一的 endpoint 是 POST /v3/session/。会话是 KYC 还是 KYB 由工作流的类型决定，无需额外传入“企业”标志。 创建时建议填写的字段：

字段	用途
`workflow_id`	必填，引用你的 KYB 工作流。
`vendor_data`	你为该企业设定的标识符。将会话与企业实体绑定。
`callback_url`	可选，用户完成流程后跳转的地址。
`expected_details`	可选，格式为 `{ company_name, registry_country, registration_number }`。用于预填公司登记查询：注册国家/地区会被预选并锁定（`registry_country` 填写 `XX`，州级登记填写 `XX-YY`，例如 `US-CA`），公司名称和注册号字段会被预填，并自动执行基于所声明信息的查询；若两者都提供，则结合使用。仅用于预填，信息不一致不会产生警告。
`metadata`	可选，附加到会话上的 JSON 数据。

完整结构请参阅创建会话。

发送托管验证链接

响应中的 url 是托管验证链接。发送方式如下：

通过你自己的平台发送邮件。
以链接形式嵌入你的入驻界面。
在应用内 webview 中打开（iOS / Android / React Native）。

你可以通过白标自定义托管体验，包括 Logo、颜色、域名和邮件模板。

轮询与 Webhook

推荐使用 Webhook。处理完成后，Didit 会立即将完成事件 POST 到你订阅的 endpoint。在开发阶段，或当你的 Webhook endpoint 无法访问时，可以使用轮询：

使用指数退避轮询 GET /v3/session/{id}/decision/（起始间隔 10 秒，最长间隔 60 秒）。
当 status 为 "Approved"、"Declined" 或 "In Review" 之一时停止轮询。

高频轮询可能触发速率限制。生产环境中请始终优先使用 Webhook。

处理 Webhook

订阅你关注的事件。KYC 和 KYB 共用同一组事件，载荷中的 session_kind: "business" 用于标识企业会话事件：

status.updated：会话状态已变更。对 KYB 会话请按 session_kind === "business" 过滤。
data.updated：审核员在控制台中编辑了登记数据或关键人员信息，或登记机构报告了变更。当申请人上传证件或提交关键人员信息时不会发送此事件，请改为关注 status.updated。同样需要按 session_kind 过滤。
business.status.updated / business.data.updated：关联的企业实体已发生变更。

完整事件目录请参阅 KYB Webhook。签名验证和重试机制请参阅 Webhook 参考文档。

处理决策

switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}

有关完整的状态流转，请参阅 KYB 状态；有关解释决策原因的标签，请参阅 KYB 警告。

重新提交流程

当企业验证（KYB）会话转为 Resubmitted（或某项功能被标记为需要重新提交）时，企业需要上传修正后或补充的数据。你可以：

重新发送同一个 url，托管流程会从需要重新提交的环节继续。
重新生成失效的关键人员链接：若某相关人员的子 KYC 会话已被删除，或在其开始前已过期，可使用重新生成关键人员 KYC 会话为其创建新会话。
在 Business Console 中创建案件，在内部跟踪多次往返沟通。

在你自己的前端运行各步骤

证件和关键人员步骤也可以通过你的服务器，使用你的 API 密钥来驱动。这样，界面由你掌控，验证和决策仍由 Didit 完成。每个调用都限定于该 KYB 会话，需要 write:businesses 权限（读取已提取的相关方信息时也可使用 read:businesses 或 read:sessions），并执行与托管页面相同的检查、计费和步骤推进。

会话处于 KYB 证件步骤时，上传企业证件。
读取证件中列出的相关方，包括股东和股权比例，并将其展示给申请人。
创建、编辑和删除相关方草稿。草稿不会被视为已申报，也不产生费用。
提交草稿。Didit 会决定哪些相关方需要验证，为每位相关方创建 KYC 会话，并返回其 kyc_session_url，供你发送或嵌入。
与托管流程一样，从会话中读取汇总后的决策。

若会话处于其他步骤时发起调用，将返回 409 kyb_step_mismatch 及其所在的步骤；若会话已结束，则返回 409 kyb_session_not_writable。

企业档案聚合

如果你在创建会话时传入 vendor_data，Didit 会将该企业的所有会话聚合到同一个企业实体中。你可以直接使用实体的 features 映射，无需遍历会话，即可判断该企业当前是否已完成全面验证。优势包括：

定期的重新 KYB 流程会追加到同一份企业档案中。
针对同一 vendor_data 进行的交易监控会携带该企业的风险背景信息。
关联到用户实体的实际受益人和管理人员会建立跨实体关系。

最佳实践

实践	原因
始终传递 `vendor_data`	没有它，会话会被孤立，无法被聚合。
使用 Webhook，而非轮询	延迟更低，且不会对速率限制造成压力。
验证 Webhook 签名	可防止伪造事件。
在您的系统中存储 `session_id`	用于获取决策结果并生成 PDF。
使用 `metadata` 为会话添加标签	简化报告与调试。
设置测试工作流	在投入生产环境前，使用沙盒工作流进行集成测试。

错误处理

场景	响应
无效的 `workflow_id`	`400 Bad Request`
使用相同 `vendor_data` 的重复会话	会创建新会话，这是有意为之，因为预期会进行重新验证。
企业所在国家/地区不在工作流允许的国家/地区范围内	注册信息核查会触发 `KYB_COUNTRY_RESTRICTED` 警告。
企业搜索期间注册信息服务提供方中断	`POST /v3/kyb/search/` 返回 `502`，并附带 `code: "kyb_registry_provider_unavailable"`。不计费。可重试，或根据 `code` 分支处理，以提供手动输入企业信息的选项。在 Didit 托管流程中，企业会自动转入手动输入，而不是只能重试的错误。详见 KYB 注册表搜索。
速率限制	`429 Too Many Requests`，并带有 `Retry-After` 请求头。

完整的速率限制参考文档。

后续步骤

Webhook

每个 KYB 事件及其 payload。

状态

状态机参考。

响应结构

解读 KYB 决策结果。

​架构

​身份验证

​创建会话

​发送托管验证链接

​轮询与 Webhook

​处理 Webhook

​处理决策

​重新提交流程

​在你自己的前端运行各步骤

​企业档案聚合

​最佳实践

​错误处理

​后续步骤

Webhook

状态

响应结构

架构

身份验证

创建会话

发送托管验证链接

轮询与 Webhook

处理 Webhook

处理决策

重新提交流程

在你自己的前端运行各步骤

企业档案聚合

最佳实践

错误处理

后续步骤