全部產品
Search

搜尋本產品

    ID Verification：Initialize

    文件中心

    ID Verification：Initialize

    更新時間：Jan 31, 2026

    本文介紹如何通過調用Initialize介面發起eKYC請求。

    發起認證請求

    • 介面名：Initialize

    • 要求方法：HTTPS POST

    • 介面說明：每次開始eKYC認證流程前，通過本介面擷取transactionId，用來串聯認證請求中的各個介面。

    • QPS限量：API獨享QPS限量，詳情請參見ID Verification服務端API QPS限量說明。

    • 服務地址：

      說明

      • 內網訪問優勢：內網指阿里雲同一地區內各產品間的私人通訊網路。若您的商務服務器部署於阿里雲對應地區，請使用內網網域名稱訪問 ID Verification 服務，以獲得更安全、穩定的通訊品質。 

      • 海外訪問最佳化建議：海外網路環境複雜，建議參考服務端網路耗時分析與最佳化，最佳化整合方案，降低網路延遲及請求失敗機率。

      中國香港

      • 公網：cloudauth-intl.cn-hongkong.aliyuncs.com

      • 內網：cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

    線上調試和整合

    說明

    在調試和整合前，請確保您已完整閱讀使用OpenAPI調試和整合服務端API文檔，充分瞭解API介面在OpenAPI平台的調用方式和SDK及其代碼的擷取方式。

    您可以在OpenAPI Explorer中直接運行本介面進行調試，並產生本介面的SDK程式碼範例。

    請求參數

    名稱

    類型

    是否必選

    描述

    Example

    ProductCode

    String

    是

    要接入的產品方案。取值：

    eKYC：使用eKYC產品方案，您的使用者需要完成證件識別和活體認證整個流程。

    eKYC

    SceneCode

    String

    否

    您自訂的認證情境ID，用於後續控制台輸入此情境ID查詢相關記錄。支援長度為10位的字母、數字或底線的組合。

    1234567890

    MerchantBizId

    String

    是

    您自訂的業務唯一標識，用於後續定位排查問題。支援長度為32位的字母和數位組合，請確保唯一。

    說明

    阿里雲伺服器不會對該欄位的值進行唯一性檢查。為了更好地跟蹤，強烈建議保證欄位唯一性。

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    是

    MetaInfo環境參數，需要通過用戶端SDK擷取。更多資訊，請參見對應的用戶端整合說明。

    說明

    無須修改傳回值，直接透傳即可。

    		 

    {
  "zimVer": "3.0.0",
  "appVersion": "1",
  "bioMetaInfo": "4.1.0:1150****,0",
  "appName": "com.aliyun.antcloudauth",
  "deviceType": "h5",
  "osVersion": "iOS 10.3.2",
  "apdidToken": "",
  "deviceModel": "iPhone9,1"
}

    MerchantUserId

    String

    是

    您自訂的使用者ID，或者其他可以識別特定使用者的標識，例如手機號碼、郵箱地址等。強烈建議對該欄位的值進行預先脫敏，例如對值進行雜湊處理。

    123456789

    IdSpoof

    String

    否

    是否開啟證件防偽檢測功能：

    • Y：開啟

    • N：關閉（預設）

    Y

    DocType

    String

    是

    證件類型，以8位元字組合作為唯一標識，詳見下表。

    01000000

    Authorize

    String

    否

    是否開啟官方資料庫身份核驗：

    • T：開啟

    • F：關閉（預設）

    說明

    目前僅適用於中國內地第二代居民身份證。

    F

    SecurityLevel

    String

    否

    代表認證流程不同安全水位的模式，可選值：

    • 01：普通模式，僅適用低風險且對裝置資訊採集限制的情境。

    • 02：安全模式，相對嚴格的模式（預設）。

      說明

      • 安全模式通過 SDK 新增的裝置助手模組，基於裝置資訊識別刷臉環境的安全性，有效提升對注入攻擊的攔截能力。建議啟用此模式。

      • 在開發測試階段，測試裝置的環境特徵可能導致裝置安全助手判定存在風險，從而觸發認證失敗（Subcode 206）。建議在測試期間將模式手動設定為“01 普通模式”，以提升測試效率；正式上線時切換為“02 安全模式”，以增強認證安全性。

    02

    IdThreshold

    String

    否

    自訂OCR品質檢測閾值模式：

    • 0：標準模式

    • 1：strict 模式

    • 2：寬鬆模式

    • 3：關閉品質檢測（預設）

    0

    Model

    String

    否

    要進行活體檢測的類型：

    • LIVENESS：眨眼動作活體檢測（預設）。

    • PHOTINUS_LIVENESS：眨眼動作活體檢測和炫彩活體（PC端不支援）檢測。

    說明

    支援整合的SDK版本，請參見SDK發布記錄。

    PHOTINUS_LIVENESS

    DocVideo

    String

    否

    是否需要存證視頻。

    • N：不需要（預設）。

    • Y：認證過程中會同時採集使用者的刷臉過程視頻（1~2s視頻檔案），並通過查詢介面返回。

    說明

    因為視頻檔案較大，當網路不穩定時系統會丟棄視頻檔案，優先保障認證必要圖片傳輸。

    N

    CallbackUrl

    String

    否

    認證結果的回調通知地址，回調請求方式預設為GET，回調地址必須以https開頭。平台在完成認證後會回調該地址，並自動添加以下欄位：

    • transactionId

    • passed

    • subcode

    警告

    • 此值的傳入會在調用介面前做可訪問校正，如果傳入的地址不能在公網訪問，會返回400。

    • 回調會在認證完成後立即執行，但可能會因為網路等原因延遲，建議您優先接收用戶端側的認證完成通知，再請求查詢介面擷取認證詳情。

    https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200

    CallbackToken

    String

    否

    安全Token，由您自行產生，用於防重複、防篡改校正。

    如果設定了此值，將會在CallbackUrl回調時攜帶CallbackToken欄位。

    NMjvQanQgplBSaEI0sL86WnQplB

    AppQualityCheck

    String

    否

    是否開啟人臉嚴格品質檢測。

    • Y：開啟（預設）

    • N：不開啟

    重要

    • 此配置需要用戶端SDK的支援，如果設定開啟，但用戶端SDK沒有整合人臉品質檢測模組，則此配置視同不開啟。

    • 用戶端SDK版本需要1.2.5及以上版本。

    N

    DocPageConfig

    String

    否

    JSON字串數組格式：

    OCR_ID_BACK： 採集反面頁面

    說明

    當前僅支援中國內地身份證類型

    OCR_ID_BACK

    ShowGuidePage

    String

    否

    是否展示引導頁面開關：

    • 1（預設）：展示

    • 0：不展示

    1

    DocScanMode

    String

    否

    OCR證件掃描模式：

    • shoot（預設）：拍照

    • scan：掃描

    • auto：拍照/掃描自動切換

    shoot

    證件類型列表

    DocType

    對應證件

    01000000

    全球護照

    00000006

    香港居民身份證（2003版）

    00000008

    香港居民身份證（2018版）

    00000007

    往來港澳通行證

    00000009

    港澳居民來往內地通行證

    000000011

    澳門身份證

    000000012

    台灣居民來往大陸通行證

    00000001

    中國內地第二代居民身份證

    返回資料

    名稱

    類型

    描述

    樣本值

    HTTP Status Code

    Integer

    HTTP狀態代碼。

    200

    HTTP Body

    RequestId

    String

    請求ID。

    130A2C10-B9EE-4D84-88E3-5384FF03****

    Code

    String

    返回Code。

    Success

    Message

    String

    返回Code的詳細描述。

    success

    Result.TransactionId

    String

    整個認證流程的唯一標識。該欄位為計費統計字段，並用於發起CheckResult介面請求。

    重要

    • 當請求過程中出現錯誤時，例如參數無效，則不會返回TransactionId。

    • 建議將TransactionId與您本次商務程序的業務ID綁定並儲存在服務端，在CheckResult時從您服務端儲存提取該認證ID，發起結果查詢。

    • 擷取TransectionId或TransactionUrl成功後，需要在30分鐘內完成認證，超過時間將自動失效無法再認證。

    hksb7ba1b28130d24e015d6********

    Result.Protocol

    String

    認證標準加密協議。

    建議擷取該參數並傳遞給用戶端 SDK。用戶端 SDK 將基於此參數減少網路互動，並支援動態網路切換，以提升使用者體驗。

    hksb7ba1b28130d24e015d*********

    返回Code

    HTTP狀態代碼

    Code

    Message描述

    200

    Success

    請求成功。

    400

    MissingParameter

    參數不可為空。

    InvalidParameter

    非法參數。

    401

    Forbidden.ExceptionRepeatedInvoke

    異常重複調用次數超限。

    403

    Forbidden.RAMUserAccessDenied

    需要給RAM使用者授予AliyunAntCloudAuthFullAccess操作許可權。更多資訊，請參見授權RAM使用者訪問服務。

    Forbidden.AccountAccessDenied

    確保您開通了ID verifycation，並且保證賬戶未欠費。

    Throttling.Api

    API限流攔截。

    500

    InternalError

    系統內部錯誤，請反饋工程師排查。

    503

    ServiceUnavailable

    服務不可用，請反饋工程師排查。