KYC · 客户准入

注册客户、恢复或启动执行、提交节点数据并跟踪案件审核结论。

流程概览

使用 eventType KYC_EVENT。注册客户后先检查是否已有执行；仅在无匹配时启动，依次提交等待中的节点，并跟踪案件最终结论。KYC 只是控制台显示名。

步骤 1 — 注册客户

接口: workflow.applicant.register POST

{
  "customerId": "C_abc123",
  "email": "john@example.com"
}

响应:

{
  "apiCode": 200,
  "data": {
    "code": 200,
    "data": { "customerId": "C_abc123", "isNew": true },
    "msg": "success"
  }
}

2. 恢复或启动工作流

2.1 检查已有执行

接口: workflow.apply.query POST

按 eventType + source + customerId 查询该客户是否已有执行。只读 — 不触发新执行、不计费。使用 apiVersion 1.0.0。

• 断点恢复 — 调用 submit 后超时或宕机、未拿到 executionId：先 query，命中则直接拿回 executionId 继续轮询，避免重复提交（submit 计费）。
• 提交防重 — 上游重试导致同一客户可能重复发起：query 命中 RUNNING / APPROVED 时跳过 submit。

请求

{
  "eventType": "KYC_EVENT",
  "source": "API",
  "customerId": "C_abc123"
}

响应

{
  "apiCode": 200,
  "apiMsg": "OK",
  "data": {
    "code": 200,
    "executionId": "exec-7208f03b931e4897",
    "status": "RUNNING"
  }
}

2.2 启动工作流

接口: workflow.apply.submit POST

{
  "eventType": "KYC_EVENT",
  "source": "API",
  "data": {
    "customerId": "C_abc123",
    "referenceId": "onboarding-uuid-001"
  }
}

保存返回的 executionId — 后续所有接口调用均需使用。关于 apiVersion 2.0.0 与本工作流共用的 Case 结论字段（caseStatus / riskScore），见 工作流生命周期 API → 发起 与 查询状态与审核结论。

workflow.apply.submit 使用 apiVersion 2.0.0。workflowId 为可选：传入已发布的工作流 ID 可明确选择工作流；留空则按 eventType + source 路由。请持久保存 executionId。业务层 data.code 为 403 表示事件额度不足；再次提交前请管理员补充额度。

步骤 3 — 轮询状态

接口: workflow.execution.status POST

{
  "executionId": "exec-abc123def456"
}

当 status = WAITING 时的关键字段:

• currentNode.nodeType → 决定调用哪个接口
• currentNode.callbackKey → 提交数据时必传
• currentNode.metadata → 节点专属配置

除执行状态外，还应读取 caseNo、caseStatus、riskScore 和 resolvedAt。UNASSIGNED、UNDER_REVIEW 和 RETURNED 表示人工处理；OTHER_GROUP 表示流程仍在其他组或节点中继续。请持续轮询至 caseStatus 为 APPROVED、REJECTED 或 CLOSED，或执行为 FAILED 或已确认取消。人工处理时采用 30–60 秒间隔，自动处理时采用 3–5 秒间隔。不能仅凭执行状态替代案件审核结论。

步骤 4 — 提交节点数据

每次提交响应都包含 nextStep 对象，可直接使用以进入下一步 — 无需每次提交间轮询。仅在恢复会话或等待最终结果时轮询。

身份证件 (OCR)

两步操作: 先提交图片，再轮询结果。

步骤 1 — 提交: workflow.kyc.ocr POST

OCR 提交请求体：workflow.kyc.ocr

{
  "provider": "WIDTH",
  "frontImage": "s3://workflow-kyc/.../front.jpg",
  "backImage":  "s3://workflow-kyc/.../back.jpg",
  "documentType": "INTERNATIONAL_PASSPORT",
  "region": "SG",
  "executionId": "exec-abc123def456",
  "callbackKey": "kyc:ocr:exec-abc123def456:...",
  "referenceId": "onboarding-uuid-001"
}

步骤 2 — 轮询结果: workflow.kyc.ocr.data POST

2–5 秒后轮询。OCR 通常在 5–15 秒内完成。

个人信息

接口: workflow.kyc.particular.data POST

{
  "executionId": "exec-abc123def456",
  "callbackKey": "kyc:particular:exec-abc123def456:...",
  "referenceId": "onboarding-uuid-001",
  "personData": "{\"name\":\"John Smith\",\"dateOfBirth\":\"1990-01-15\",\"nationality\":\"SG\",\"sex\":\"MALE\",\"countryOfResidence\":\"SG\",\"address\":\"123 Main St\"}"
}

活体检测

在 OpenAPI 模式下，活体检测是数据提交步骤而非交互式检测。提交 status: "PASS" 及客户照片即可。

接口: workflow.kyc.liveness.data POST

{
  "provider": "SELF",
  "status": "PASS",
  "scores": "{\"qualityScore\":1.0,\"brightnessScore\":100,\"brightnessStatus\":\"normal\"}",
  "images": "{\"faceFull\":\"s3://workflow-kyc/tenantImages/2026-04-16/customer_photo.jpg\"}",
  "executionId": "exec-abc123def456",
  "callbackKey": "kyc:liveness:exec-abc123def456:...",
  "referenceId": "onboarding-uuid-001"
}

邮箱 / 手机 OTP

步骤 1 — 发送: workflow.kyc.otp.send POST

{
  "type": "email",
  "identity": "john@example.com",
  "executionId": "exec-abc123def456",
  "callbackKey": "kyc:email:exec-abc123def456:...",
  "referenceId": "onboarding-uuid-001"
}

步骤 2 — 验证: workflow.kyc.otp.verify POST

{
  "type": "email",
  "identity": "john@example.com",
  "code": "985024",
  "executionId": "exec-abc123def456",
  "callbackKey": "kyc:email:exec-abc123def456:...",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "referenceId": "onboarding-uuid-001"
}

必传文件

接口: workflow.kyc.required.doc POST

{
  "doc": "{\"front\":{\"url\":\"s3://workflow-kyc/.../bill.pdf\",\"filename\":\"bill.pdf\",\"content_type\":\"application/pdf\",\"size\":85618}}",
  "isRequired": true,
  "docType": "UTILITY_TELEPHONE_BILL",
  "extraData": "{\"issueDate\":\"2026-03-01\"}",
  "executionId": "exec-abc123def456",
  "callbackKey": "kyc:required_doc:exec-abc123def456:...",
  "referenceId": "onboarding-uuid-001"
}

上传完所有文件后，调用 workflow.kyc.required.doc.submit 推进工作流。

必填表单

接口: workflow.kyc.required.form POST

{
  "formId": "IndividualForm",
  "formData": "{\"field_source_of_funds\":\"EMPLOYMENT\",\"field_annual_income\":\"50000-100000\"}",
  "executionId": "exec-abc123def456",
  "callbackKey": "kyc:required_form:exec-abc123def456:...",
  "referenceId": "onboarding-uuid-001"
}

提交所有表单后，调用 workflow.kyc.required.form.submit。

取消执行

接口: workflow.execution.cancel POST

{
  "executionId": "exec-abc123def456"
}

中途恢复

若流程中断，使用已保存的 executionId 调用 workflow.execution.status，即可从上一个待处理节点恢复。数据不会丢失。