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 及疑難排解。

下一步：選擇工作流程