全部產品
Search
文件中心

Financial Intelligence Engine:asyncrecognize

更新時間:Apr 21, 2026

概覽

  • API URL:/api/v1/zoloz/idrecognition/asyncrecognize

  • API 描述:該介面用於初始化非同步證件識別請求。當您需要大量調用recognize API時,為了避免因網路波動而導致響應逾時,建議使用asyncrecognize API。在API調用結束後,您可以通過asynccheckresult API非同步擷取證件驗證結果。

請求參數

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

bizId

String

32B

是

-

業務ID,業務的唯一標識,用於追蹤業務。

"trans-test-1234"

docType

String

32B

否

null

指定上傳證件的類型。

注意:

  • docType與autoDocTypes、autoDocCategory、autoDocCountryCode互斥,不可同時使用。

  • docType、autoDocTypes、autoDocCategory、autoDocCountryCode可以分別單獨使用。

"00000001003"

autoDocTypes

List<String>

200

否

null

指定證件類型列表,由系統對上傳證件進行自動分類。該參數可單獨使用或與autoDocCountrycode組合使用。

  • 銀行卡和港澳入境小票不支援自動分類。

  • 如果系統無法分類或分類結果不在傳入的autoDocTypes中,asynccheckresult API將返回NO_REQUIRED_ID。

支援的證件類型,詳見RealID和ID Recognition支援的證件類型和返回的OCR結果。

[

"08520000001",

"08520000002"

]

autoDocCategory

List<String>

-

否

null

指定證件類別,由系統對上傳證件進行自動分類。該參數可單獨使用或與autoDocCountrycode組合使用。

  • 支援的證件類別如下:

  • PASSPORT:護照

  • DRIVING_LICENSE:駕照

  • ID_CARD:身份證

  • RESIDENCE_PERMIT:居住證

  • VISA:簽證

  • ALL:所有證件

  • 如果系統無法分類或分類結果不在傳入的autoDocCategory中,asynccheckresult API將返回NO_REQUIRED_ID。

注意:當傳入autoDocCategory時,系統可能識別出新的證件類型和類別,此時asynccheckresult API返回的certType和docCategory可能歸入新的證件類別。這是由於ZOLOZ正在不斷擴充全球證件的覆蓋範圍,以支援更多證件類型。

舉例:當autoDocCategory設定為ALL時,系統會根據上傳證件自動分類,分類完成後,certType可能返回一種新的證件類型(例如00000001001),並歸類為NEW_CATEGORY。

為確保您的系統平穩適配新的證件類型,建議提前做好相容性整合措施,例如避免對返回的certType和docCategory進行強校正。

"ID_CARD"

autoDocCountrycode

List<String>

300

否

null

指定證件所屬國家或地區。支援傳ALL或符合ISO 3166-1 alpha-3標準的三位國家碼。

支援以下使用方式:

  • autoDocCountrycode單獨使用:表示傳入的證件類型屬於某個國家。

  • autoDocCountrycode+autoDocCategory:取兩個參數的交集,表示傳入的證件類型屬於某國家某類別的證件。
    舉例:autoDocCategory=ID_CARD和DRIVING_LICENSE,autoDocCountrycode=PHL,表示只允許菲律賓的身份證和駕照通過,否則提示證件類型錯誤。

  • autoDocCountrycode+autoDocTypes:取兩個參數的交集,表示傳入的證件類型列表屬於某個國家。
    注意:

  • autoDocTypes必須包含通用護照(00000001003或00000001006)才能組合使用,否則系統將攔截該請求。

  • autoDocCountrycode必須涵蓋傳入的autoDocTypes列表中的國家範圍,否則系統將攔截該請求。

舉例:

  • autoDocTypes=通用護照(00000001003或00000001006)和菲律賓駕照(00630000004),autoDocCountrycode=AUS,系統將攔截該請求。

    • autoDocTypes=通用護照(00000001003或00000001006)和澳大利亞永久居民身份證(00610000009),autoDocCountrycode=AUS,表示只允許澳大利亞的護照和永久居民身份證通過,否則系統將提示證件類型錯誤。

注意:

  • 如果系統無法分類或分類的證件國家不在autoDocCountrycode中,asynccheckresult API將返回NO_REQUIRED_ID。

  • 當傳入autoDocCountrycode時,系統可能識別出新的證件國家,此時asynccheckresult API返回的certCountry和certCountryCode可能歸入新的證件國家。這是由於ZOLOZ正在不斷擴充全球證件的覆蓋範圍,以支援更多證件類型。
    為確保您的系統平穩適配新的證件國家,建議提前做好相容性整合措施,例如避免對返回的certType、docCategory、certCountry和certCountryCode進行強校正。

[

"CHN",

"PHL"

]

frontPageImage

String

5MB

是

-

證件的正面照,支援Base64編碼的JPG、JPEG、PNG、BMP格式。

注意:frontPageImage和backPageImage兩張圖片的總大小不能超過5MB,如果圖片過大,建議壓縮後再上傳,以免造成系統錯誤。

"/9j/4AA..[omitted]..PxA="

backPageImage

String

5MB

否

null

證件的背面照,支援Base64編碼的JPG、JPEG、PNG、BMP格式。

注意:frontPageImage和backPageImage兩張圖片的總大小不能超過5MB,如果圖片過大,建議壓縮後再上傳,以免造成系統錯誤。

"/9j/4AA..[omitted]..PxA="

operationMode

String

32

否

STANDARD

為身分識別驗證配置操作模式。取值如下:

  • CLOSED:所有的演算法和風控規則都未開啟。該操作模式可用於測試情境,測試進程不受演算法和風控規則的影響。

  • STANDARD:推薦的標準模式。

  • LOOSE:相對寬鬆的模式,可用於低風險情境。

  • STRICT:相對嚴格的模式,可用於高風險情境。

"STANDARD"

sceneCode

String

64

否

null

情境碼,用於為資料分析指定不同的業務情境。

當需要區分不同業務情境中的資料表現時,建議根據業務用途為sceneCode欄位設定不同的值,例如login、riskVerify、payment、changePassword。該設定不會影響業務的正常運行。

"changePassword"

userId

String

64

否

null

商戶的使用者ID或其他可用於識別某一使用者的標識,例如手機號碼、電子郵件地址等。

建議對userId欄位的值進行預脫敏,例如進行雜湊處理。

"trans-abc-1234"

productConfig

ProductConfig

-

否

null

為IDR產品提供更精細化的控制,詳見ProductConfig。

參考請求樣本

ProductConfig欄位說明

欄位名稱

資料類型

最大長度

是否必填

預設值

描述

樣本值

pageInfoCheck

Array

-

否

null

在證件防偽檢測中進行頁面資訊檢查,詳細檢查項,請參見證件防偽檢測組件。

說明:頁面資訊檢查僅適用於以下證件類型:

  • 中國香港身份證

  • 馬來西亞大馬卡(MyKad)

  • 新加坡國民身份證(Citizen Card)

  • 新加坡永久居民卡(Permanent Resident Card)

[

{"name":"id"},

{"name":"symbol"},

{"name":"name"}

]

consistencyCheck

List<ConsistencyCheckItem>

-

否

null

是否進行一致性檢查。一致性檢查僅適用於部分證件的特定欄位,詳見ConsistencyCheckItem。

[

{

"type": "commonConsistencyCheck"

},

{

"details": [

"NAME",

"SEX"

],

"type": "mrzVisualConsistencyCheck"

},

{

"valueRange": [

"CHN",

"PHL"

],

"type": "passportCountryCheck"

}

]

allowExpiredDocument

String

-

否

不同的證件類型有不同的預設值:

  • Y:除護照(docType=00000001003)外的所有證件

  • N:護照(docType=00000001003)

已到期的證件是否可以通過驗證。取值:

  • Y:已到期的證件可以通過驗證。

  • N:已到期的證件不能通過驗證。當檢測到證件到期時,IDR流程會失敗。

說明:

  • 如果傳入除Y和N之外的值,系統將返回INVALID_ARGUMENT。

  • 中國香港一代身份證(docType=08520000001)的到期攔截機制,將嚴格按照香港政府身份證換領流程的要求執行。

"N"

cropFaceImageFromDoc

String

1

否

N

是否從採集的證件圖片中裁剪出人臉圖片。取值如下:

  • Y:是

  • N:否

"Y"

enableOCR

String

-

否

N

是否開啟OCR功能。取值如下:

  • Y:開啟

  • N:不開啟

"Y"

spoofMode

String

10

否

CLOSED

證件防偽等級。取值如下:

  • CLOSED:所有的防偽演算法都未開啟。該等級可用於測試情境,測試進程不受演算法的影響。

  • STANDARD:推薦的標準等級。

  • LOOSE:預留等級,暫不支援使用。

  • STRICT:預留等級,暫不支援使用。

"STANDARD"

deeperMode

String

10

否

CLOSED

AIGC攻擊檢測的Deeper等級,Deeper檢測功能的詳細介紹,請參見什麼是Deeper。該參數支援以下取值:

  • CLOSED:Deeper的所有能力均不開啟,例如AIGC檢測演算法、終端風險檢測等。如果業務情境不需要AIGC攻擊檢測,則無需開啟。

  • STANDARD:推薦的標準等級。

  • LOOSE:相對寬鬆的等級,可用於低風險情境。

  • STRICT:相對嚴格的等級,可用於高風險情境。

注意:需要先購買Deeper產品,才能使用該功能。

"STANDARD"

ConsistencyCheckItem類型說明

commonConsistencyCheck

欄位名稱

資料類型

取值範圍

描述

支援的證件 / 國家或地區 / 證件類型

OCR一致性檢查支援欄位

type

String

commonConsistencyCheck

對證件防偽檢測中的OCR欄位進行一致性檢查。

大馬卡 / 馬來西亞 / 00600000001

  • 證件正面:ID_NUMBER

  • 證件背面:ID_NUMBER_BACK前12位元字

mrzVisualConsistencyCheck

欄位名稱

資料類型

取值範圍

描述

支援的證件 / 國家或地區 / 證件類型

OCR一致性檢查支援欄位

type

String

mrzVisualConsistencyCheck

對證件防偽檢測中機讀區和視讀區的OCR欄位進行一致性檢查。

-

-

details

List<String>

詳見RealID和ID Recognition支援的證件類型和返回的OCR結果。

在details中指定OCR欄位進行一致性檢查。

  • 當type設定為mrzVisualConsistencyCheck時,必須傳入details欄位。

  • 僅允許傳入證件類型所支援的OCR欄位。

MyVisa / 馬來西亞 / 00600000011

  • NAME

  • SEX

護照(含機讀區和視讀區)/ 所有國家或地區 / 00000001006

  • ID_NUMBER

  • COUNTRY_CODE

  • EXPIRY_DATE

  • DATE_OF_BIRTH

往來港澳通行證 / 中國大陸 / 00860000011

  • ID_NUMBER

  • DATE_OF_EXPIRY

passportCountryCheck

欄位名稱

資料類型

取值範圍

描述

支援的證件 / 國家或地區 / 證件類型 / OCR一致性檢查支援欄位 / 預設國家代碼

type

String

passportCountryCheck

檢查OCR結果中的COUNTRY_CODE與系統檢測到的國家是否一致。

-

valueRange

List<String>

應與預設國家代碼一致

OCR結果中的COUNTRY_CODE應在valueRange範圍內。

當type設定為passportCountryCheck時,必須傳入valueRange欄位,各證件支援的valueRange,詳見RealID和ID Recognition支援的證件類型和返回的OCR結果。

以下證件的valueRange為證件所屬國家或地區對應的預設國家或地區代碼所組成的列表。

  • 中國大陸護照 / 00860000888 / COUNTRY_CODE / CHN

  • 中國台灣護照 / 08860000002 / COUNTRY_CODE / TWN

  • 中國澳門護照 / 08530000002 / COUNTRY_CODE / CHN

  • 菲律賓舊版護照 / 00630000031 / COUNTRY_CODE / PHL

  • 菲律賓新版護照 / 00630000032 / COUNTRY_CODE / PHL

每一項都應符合ISO_3166-1_alpha-3標準

以下證件的valueRange為列表,且每一項都應符合ISO_3166-1_alpha-3標準。

  • 國際護照(僅含機讀區) / 00000001003 / COUNTRY_CODE

  • 國際護照(含機讀區和視讀區)/ 00000001006 / COUNTRY_CODE

返回參數

欄位名稱

資料類型

必須返回

描述

樣本值

result

Result

是

API請求結果,包含結果狀態、結果碼和結果訊息。

{

"resultCode": "PROCESSING",

"resultStatus": "S",

"resultMessage": "It is still under processing"

}

transactionId

String

是

事務ID。

說明:僅當交易進入處理階段後系統才會返回transactionId。如果在開始處理交易之前發生錯誤,系統不會返回transactionId。包括但不限於以下情況:

  • 請求參數非法,例如入參格式錯誤或缺失必傳參數。

  • 請求未能成功到達伺服器,例如網路問題或網關故障。

  • 系統限流導致請求被拒絕。

"G000000005FID2020030400000000000157****"

Result欄位說明

欄位名稱

資料類型

必須返回

描述

樣本值

resultCode

String

是

結果碼。

  • INVALID_ARGUMENT:輸入參數無效。

  • bizId為null或Null 字元串。

  • docType為null或無效。

  • frontPageImage或backPageImage為空白,或編碼格式不正確。

  • PROCESSING:正在處理中。

  • SYSTEM_ERROR:其他內部錯誤。

"PROCESSING"

resultStatus

String

是

結果狀態。

"S"

resultMessage

String

是

結果資訊。

"It is still under processing"

程式碼範例

請求樣本

POST /api/v1/zoloz/idrecognition/asyncrecognize HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 5X67656YXXXXXX
Request-Time: 2024-01-04T12:08:56+05:30
Signature: algorithm=RSA256, signature=xxxxxxxxxxxx

{
  "bizId": "trans-test-1234",
  "autoDocTypes":["08520000001","08520000002"],
  "frontPageImage": "/9j/4AA..[omitted]..PxA=",
  "backPageImage": "/9j/4AA..[omitted]..PxA=",
  "productConfig": {
    "deeperMode": "STANDARD",
    "consistencyCheck": [
      {
        "type": "commonConsistencyCheck"
      },
      {
        "details": [
          "NAME",
          "SEX"
        ],
        "type": "mrzVisualConsistencyCheck"
      },
      {
        "valueRange": [
          "CHN",
          "PHL"
        ],
        "type": "passportCountryCheck"
      }
    ],
    "pageInfoCheck": [
            {
                "name": "id"
            },
            {
                "name": "symbol"
            },
            {
                "name": "name"
            }
        ],
    "allowExpiredDocument": "Y",
    "cropFaceImageFromDoc": "Y",
    "enableOCR": "Y",
    "spoofMode": "STANDARD"
  },
  "operationMode": "STANDARD",
  "sceneCode": "changePassword",
  "userId": "userid_1234"
}

返回樣本

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2024-01-19T21:56:15-0800
Signature: algorithm=RSA256, signature=xxxxxxxxxxxxxxxxxx

{
  "transactionId": "G000000005FID2020030400000000000157****",
  "result": {
    "resultCode":"PROCESSING",
    "resultStatus":"S",
    "resultMessage":"It is still under processing"
  }
}