OpenAPI · REST 参考

REST 请求结构、身份验证、工作流生命周期、错误处理、配置与文件上传。

快速入门

基础地址

请求格式

POST {base_url}?api={apiName}&apiVersion={apiVersion}&apiKey={apiKey}&sign={sign}
Content-Type: application/json
x-domain: {domainId}

{JSON body}

发起工作流

接口: workflow.apply.submit POST

按 eventType + source 路由到当前已发布（PUBLISHED）的工作流并发起执行。

apiVersion 版本

请求

{
  "eventType": "KYC_EVENT",
  "source": "API",
  "data": {
    "customerId": "demo-customer-001",
    "fullName": "ZHANG SAN",
    "dateOfBirth": "1990-01-01",
    "nationality": "CN"
  },
  "workflowId": ""
}

响应

{
  "apiCode": 200,
  "apiMsg": "OK",
  "data": {
    "code": 200,
    "message": null,
    "executionId": "exec-7208f03b931e4897",
    "status": "EXECUTING",
    "requestId": "...",
    "sync": false
  }
}

工作流 ID 位置：在 WIDTH One Platform 打开 Workflow，在工作流列表中复制工作流名称旁显示的 Workflow ID，并在使用 apiVersion 2.0.0 时通过 workflowId 传入。

响应格式

成功:

{
  "apiCode": 200,
  "apiMsg": "OK",
  "data": {}
}

错误:

{
  "apiCode": 999001,
  "apiMsg": "SIGN_ERROR",
  "data": null
}

按顺序读取响应：先看 HTTP 状态，再看 apiCode；若接口使用业务信封，再看 data.code 和 data.data。仅 apiCode 为 200 不代表业务成功，仍须检查该接口的业务结果。

错误码

身份验证

签名计算

sign = HmacSHA256(apiSecret, requestBody)

密钥和请求体均使用 UTF-8 编码。结果为 64 位小写十六进制字符串。 签名必须基于 HTTP body 的原始字节计算。

代码示例

Java:

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); // Java 17+

Python:

import hmac, hashlib

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

Node.js:

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

幂等性

所有节点数据提交接口均基于 callbackKey 幂等。重复提交相同 callbackKey 是安全的 — 仅首次成功提交生效，因此网络超时后可放心重试。

交互模型

• 客户端 (App/Web): 链式驱动流程。 前端由每次提交响应中返回的 nextStep 对象驱动，无需全局轮询。仅对异步任务（如 OCR）轮询专用 .data 接口。
• 服务端 (租户后端): 最终状态轮询。 最后一个用户输入节点完成后，以宽松间隔（1–5 分钟）轮询 workflow.execution.status，直至达到终态。

工作流生命周期 API

工作流生命周期 API 是纯服务端对接路径：由你的后端发起一个事件、轮询执行状态与 Case（案件，一次审核的记录单元）审核结论，并在请求丢失或被重试时查询该客户是否已有进行中的执行。三个接口构成一个闭环。

它与 KYC / KYB 章节记录的节点驱动 SDK 路径不同：那里客户端逐个节点提交数据，这里由平台从头到尾跑完整个已发布工作流，你只需发起并轮询。

流程概览

1. 发起
2. 轮询状态
3. 审核结论

workflow.apply.query 位于这个循环之前，作为恢复路径：当一次 submit 可能已经发生过（超时或上游重试）时先调用它，避免重复提交。

计费

查询状态与审核结论

接口: workflow.execution.status POST

只读接口 — 不触发执行、不计费。executionId 按租户（及 x-domain）校验归属，无法跨租户查询。使用 apiVersion 1.0.0。

请求

{ "executionId": "exec-7208f03b931e4897" }

响应

{
  "apiCode": 200,
  "apiMsg": "OK",
  "data": {
    "executionId": "exec-7208f03b931e4897",
    "status": "COMPLETED",
    "caseNo": "C001443",
    "caseStatus": "REJECTED",
    "riskScore": 45.0,
    "resolvedAt": 1784714818000
  }
}

状态语义

各阶段响应示例

阶段 1 — 自动节点执行中，Case 尚未生成（到达决策节点前的短暂窗口）：

{ "apiCode": 200, "apiMsg": "OK",
  "data": { "executionId": "exec-xxxx", "status": "RUNNING" } }

无 caseStatus 字段 → 尚未生成 Case，继续轮询。

阶段 2 — Case 已生成，等待人工处理：

{ "apiCode": 200, "apiMsg": "OK",
  "data": { "executionId": "exec-xxxx", "status": "RUNNING",
            "caseNo": "C001286", "caseStatus": "UNASSIGNED", "riskScore": 49.17 } }

人工处理期间 caseStatus 反映进度：UNASSIGNED（队列待分配）→ UNDER_REVIEW（审核员领取后）；退回重做时为 RETURNED。

阶段 3 — 已出结论（人工审核或自动决策）：

{ "apiCode": 200, "apiMsg": "OK",
  "data": { "executionId": "exec-xxxx", "status": "COMPLETED",
            "caseNo": "C001443", "caseStatus": "REJECTED", "riskScore": 45.0,
            "resolvedAt": 1784714818000 } }

轮询退出条件

每次执行到达决策节点后都会生成 Case（人工审核 → UNASSIGNED / UNDER_REVIEW；自动通过/拒绝/关闭 → 直接产生终态 Case），因此：

caseStatus in {APPROVED, REJECTED, CLOSED}
OR status == FAILED
OR status == CONFIRMED_CANCELLATION_ENUM

恢复查询（防重 / 断点恢复）

接口: 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": "demo-customer-001"
}

响应

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

错误码

代码示例

curl（完整闭环）

API_KEY="ak_xxx"
API_SECRET="sk_xxx"
DOMAIN_ID="{domainId}"
BASE_URL="https://api-gateway-platform.width.com/gateway"

# HMAC-SHA256 sign helper / 签名助手
sign() { printf "%s" "$1" | openssl dgst -sha256 -mac HMAC -macopt key:"$API_SECRET" | sed 's/^.* //'; }

# 0. (optional) recovery query — dedup before submit / 恢复查询防重
BODY='{"eventType":"KYC_EVENT","source":"API","customerId":"demo-customer-001"}'
curl -s -X POST "${BASE_URL}?api=workflow.apply.query&apiVersion=1.0.0&apiKey=${API_KEY}&sign=$(sign "$BODY")" \
  -H "Content-Type: application/json" -H "x-domain: ${DOMAIN_ID}" -d "$BODY"

# 1. submit / 发起工作流
BODY='{"eventType":"KYC_EVENT","source":"API","data":{"customerId":"demo-customer-001","fullName":"ZHANG SAN"},"workflowId":""}'
curl -s -X POST "${BASE_URL}?api=workflow.apply.submit&apiVersion=2.0.0&apiKey=${API_KEY}&sign=$(sign "$BODY")" \
  -H "Content-Type: application/json" -H "x-domain: ${DOMAIN_ID}" -d "$BODY"
# -> record data.executionId / 记下 data.executionId

# 2. poll status / 轮询执行状态
BODY='{"executionId":"exec-7208f03b931e4897"}'
curl -s -X POST "${BASE_URL}?api=workflow.execution.status&apiVersion=1.0.0&apiKey=${API_KEY}&sign=$(sign "$BODY")" \
  -H "Content-Type: application/json" -H "x-domain: ${DOMAIN_ID}" -d "$BODY"

Python（轮询循环）

import hashlib, hmac, json, os, time, requests

GATEWAY = "https://api-gateway-platform.width.com/gateway"
API_KEY = os.environ["WIDTH_API_KEY"]
API_SECRET = os.environ["WIDTH_API_SECRET"]
DOMAIN_ID = os.environ["WIDTH_DOMAIN_ID"]
# Supply only the cancellation enum verified by WIDTH engineering.
# Do not guess between the conflicting spellings in the reference.
CANCELLED_STATUS = os.environ["WIDTH_CONFIRMED_CANCEL_STATUS"]

def call(api, version, payload):
    body = json.dumps(payload, separators=(",", ":"))
    signature = hmac.new(API_SECRET.encode(), body.encode(), hashlib.sha256).hexdigest()
    response = requests.post(GATEWAY,
        params={"api": api, "apiVersion": version, "apiKey": API_KEY, "sign": signature},
        headers={"Content-Type": "application/json", "x-domain": DOMAIN_ID},
        data=body, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result.get("apiCode") != 200:
        raise RuntimeError(result)
    data = result.get("data")
    if isinstance(data, dict) and data.get("code", 200) != 200:
        raise RuntimeError(data)
    return data

identity = {"eventType": "KYC_EVENT", "source": "API", "customerId": "demo-customer-001"}
recovered = call("workflow.apply.query", "1.0.0", identity)
if recovered and recovered.get("status") == "APPROVED":
    print(recovered)
else:
    if recovered and recovered.get("status") == "RUNNING":
        execution_id = recovered["executionId"]
    else:
        submitted = call("workflow.apply.submit", "2.0.0", {
            "eventType": identity["eventType"], "source": identity["source"],
            "data": {"customerId": identity["customerId"], "fullName": "ZHANG SAN"},
            "workflowId": ""})
        execution_id = submitted["executionId"]
        # Persist execution_id before polling; recover after an interrupted submit.
    while True:
        state = call("workflow.execution.status", "1.0.0", {"executionId": execution_id})
        if not isinstance(state, dict):
            raise RuntimeError("Verify executionId, apiKey and x-domain; no execution returned")
        if state.get("caseStatus") in ("APPROVED", "REJECTED", "CLOSED") or state.get("status") in ("FAILED", CANCELLED_STATUS):
            print(state)
            break
        time.sleep(30 if state.get("caseStatus") in ("UNASSIGNED", "UNDER_REVIEW", "RETURNED") else 5)

常见问题

配置

在启动工作流前，获取平台配置数据（国家列表、证件类型、表单模板等）。

接口: prepare.avira.config POST

{
  "keys": "particular,avira_ssic,avira_ssoc,avira_countries,avira_document_master,avira_document_default_rule,required-form,avira_phone_code,avira_entity_types,ownership_structure_layer,transaction_behaviour,product_service_complexity,source_of_wealth,avira_source_of_funds"
}

配置项

文件上传

需要 S3 URI 的接口（证件、照片等），需先通过此接口上传文件。

步骤 1 — 获取上传令牌

接口: storage.upload.token POST

请求体: {}。令牌有效期 15 分钟。

响应:

{
  "apiCode": 200,
  "data": {
    "uploadToken": "a1b2c3d4e5f6...",
    "expiresIn": 900
  }
}

步骤 2 — 上传文件

存储服务地址:

Multipart 上传:

curl -X POST "${STORAGE_URL}/api/v1/upload/file" \
  -F "uploadToken=a1b2c3d4e5f6..." \
  -F "file=@passport_front.jpg"

Base64 上传:

curl -X POST "${STORAGE_URL}/api/v1/upload" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadToken": "a1b2c3d4e5f6...",
    "image": "data:image/jpeg;base64,/9j/4AAQ...",
    "filename": "passport_front.jpg"
  }'

响应:

{
  "apiCode": 200,
  "data": {
    "url": "s3://workflow-kyc/tenantImages/2026-04-16/abc123.jpg",
    "filename": "passport_front.jpg",
    "content_type": "image/jpeg",
    "size": 245760
  }
}

错误处理与重试策略