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，即可從上一個待處理節點恢復。數據不會丟失。