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
  }
}

錯誤處理與重試策略