WIDTH Identity 开发者文档

WIDTH Identity 提供完整的身份核验与合规平台，支持 KYC、KYB、交易筛查及持续监控工作流，可通过 REST API 以及适用于 Web、iOS、Android 和 Flutter 的即插即用 SDK 接入。

核心功能

平台通过 REST API 支持 KYC、KYB、交易筛查及持续监控。Web 和移动端 SDK 为 KYC 和 KYB 提供由平台管理的核验体验。

集成方式

提供三种主要集成方式。使用 OpenAPI 可获得完整的后端控制能力；使用 SDK 则可接入由平台管理的核验体验。

环境

提供两个环境： 预发布环境（staging） 用于开发， 生产环境（production） 用于正式流量。请使用下表中对应环境的网关、存储服务和控制台。

凭证

请根据集成方式和环境选择凭证。移动端 SDK 凭证与 Web SDK 会话令牌的配置方式不同。

获取方式

1. 登录对应环境的 One Platform Console → API & Integration 页面：
   • 预发布环境 API 凭证
   • 生产环境 API 凭证
2. 点击 Generate ，生成集成所需类型的凭证。
3. 复制并妥善保存凭证。 apiSecret 仅显示一次。

对于 Web SDK，由后端为 sdk.credentials 请求签名，并将会话令牌及选定的 domainId 返回给浏览器。每次核验都应签发新令牌，不要缓存或重复使用。请参阅 Web SDK 会话令牌参考（英文）。

开始使用

先完成控制台配置，运行首次核验并确认最终决策，再连接下游业务流程。

控制台准备工作

1. 选择环境。 使用 预发布环境控制台 进行开发，并使用生产环境控制台处理正式流量。
2. 确认 Domain（业务单元）。 Domain 用于隔离不同业务线或地区的工作流、成员和数据。新租户包含一个 DEFAULT Domain。可在以下位置管理其他 Domain： Admin Console → Domains / Business Units。
3. 生成所需凭证。 请按照 凭证 部分的说明，获取 OpenAPI、移动端 SDK 或 Web SDK 的接入凭证。
4. 配置并发布工作流。 在控制台中，为所需事件类型和来源渠道发布工作流。个人核验和企业核验对应的 API 事件值分别为 KYC_EVENT 和 KYB_EVENT；控制台中分别显示为 KYC 和 KYB。

首次核验

1. 选择 集成方式。 使用 Web 或移动端 SDK 接入由平台管理的核验界面，或使用 OpenAPI 接入自行构建的客户数据采集流程。
2. 确保环境与凭证匹配。 请使用正确的基础 URL。SDK 构建版本连接到特定环境；测试前，请确认所选软件包或构建版本与凭证对应的环境一致。
3. 启动核验。 初始化并启动 Web、 Android、 iOS 或 Flutter SDK。使用 OpenAPI 时，请先注册申请人，再启动工作流，并按照 KYC 或 KYB 指南提交所需节点数据。
4. 获取结果。 保存 executionId 并轮询 workflow.execution.status，或配置工作流 webhook。请参阅 状态与案件决策参考（英文） 和 webhook 集成指南（英文）。
5. 检查最终决策与用量。 在 Admin Console 中查看案件，并检查 Billing（账单）。已提交核验或等待人工审核的工作流均不代表最终批准。

工作流与决策模型

工作流将数据采集、筛查和规则检查串联起来，形成决策。启用自动路由时，WIDTH 根据 eventType 和来源渠道选择已发布的工作流。KYC 和 KYB 在每个来源渠道各有一个有效工作流；交易筛查可为同一事件类型配置多个工作流。 工作流生命周期 API 参考（英文） 还记录了可选参数 workflowId ，适用于版本 2.0.0。

用户完成输入步骤后，将运行自动检查与决策步骤。部分案件需要经过人工审核才能获得最终决策。使用 Webhook Action 节点 获取某个步骤的输出，或使用 Decision Webhook 获取最终的批准或拒绝决策，以及对应的操作、代码、原因和标签。

请在 工作流层面设置失败处理方式：

• Strict（严格，默认）： 任一节点失败都会导致工作流失败。
• Lenient（宽松）： 仅关键节点失败才会导致工作流失败。
• Fully tolerant（完全容错）： 无论节点是否失败，工作流都会继续运行。

用量与配额

打开 Admin Console → Billing ，查看当前套餐及本计费周期的用量统计：API Calls（API 调用次数）、Cases Processed（已处理案件数）、Workflows（工作流）和 Team Members（团队成员）。

• 筛查操作在预发布环境和生产环境中都会消耗配额。
• 如果网关返回 999501 REQUEST_API_EXCEED_LIMIT，请联系支持团队提高限额。重试前，请查阅 网关错误参考（英文） 。

快速开始：请求签名

每个 OpenAPI 请求都使用 HMAC-SHA256 对请求体进行签名，并将签名作为 sign 查询参数附加到 URL。

sign = HmacSHA256(apiSecret, requestBody)

密钥和请求体均使用 UTF-8 编码，签名结果为 64 个字符的小写十六进制字符串。

import hmac, hashlib

sign = hmac.new(
    api_secret.encode('utf-8'),
    request_body.encode('utf-8'),
    hashlib.sha256
).hexdigest()

const crypto = require('crypto');

const sign = crypto
  .createHmac('sha256', apiSecret)
  .update(requestBody, 'utf8')
  .digest('hex');

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(apiSecret.getBytes("UTF-8"), "HmacSHA256"));
byte[] hash = mac.doFinal(requestBody.getBytes("UTF-8"));
String sign = HexFormat.of().formatHex(hash);

请参阅 身份认证参考 ，了解完整的请求结构，包括请求头、查询参数及完整示例。

更多集成指南

以下主题可参阅 开发者参考指南（英文）：

• 核验链接 ：生成托管式 KYC 或 KYB 核验链接，使用 sdk.launch.link.generate。
• 姓名与名称筛查 ：筛查个人或公司，使用 MANUAL_CASE_EVENT。
• 快速筛查 API ：无需创建客户或配置工作流即可执行单次筛查，使用 quickscan.submit、 quickscan.detail 和 quickscan.hits。
• Web3 交易筛查 ：执行区块链交易筛查，使用 WEB3_TRANSACTION_EVENT。
• Webhook 集成 ：涵盖控制台设置、请求签名、响应处理、Decision Webhook 及故障排查。

下一步：选择工作流