概覽
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 | 指定上傳證件的類型。
注意:
| "00000001003" |
autoDocTypes | List<String> | 200 | 否 | null | 指定證件類型列表,由系統對上傳證件進行自動分類。該參數可單獨使用或與
支援的證件類型,詳見RealID和ID Recognition支援的證件類型和返回的OCR結果。 | [ "08520000001", "08520000002" ] |
autoDocCategory | List<String> | - | 否 | null | 指定證件類別,由系統對上傳證件進行自動分類。該參數可單獨使用或與
注意:當傳入 舉例:當 為確保您的系統平穩適配新的證件類型,建議提前做好相容性整合措施,例如避免對返回的 | "ID_CARD" |
autoDocCountrycode | List<String> | 300 | 否 | null | 指定證件所屬國家或地區。支援傳 支援以下使用方式:
舉例:
注意:
| [ "CHN", "PHL" ] |
frontPageImage | String | 5MB | 是 | - | 證件的正面照,支援Base64編碼的JPG、JPEG、PNG、BMP格式。 注意: | "/9j/4AA..[omitted]..PxA=" |
backPageImage | String | 5MB | 否 | null | 證件的背面照,支援Base64編碼的JPG、JPEG、PNG、BMP格式。 注意: | "/9j/4AA..[omitted]..PxA=" |
operationMode | String | 32 | 否 | STANDARD | 為身分識別驗證配置操作模式。取值如下:
| "STANDARD" |
sceneCode | String | 64 | 否 | null | 情境碼,用於為資料分析指定不同的業務情境。 當需要區分不同業務情境中的資料表現時,建議根據業務用途為 | "changePassword" |
userId | String | 64 | 否 | null | 商戶的使用者ID或其他可用於識別某一使用者的標識,例如手機號碼、電子郵件地址等。 建議對userId欄位的值進行預脫敏,例如進行雜湊處理。 | "trans-abc-1234" |
productConfig | ProductConfig | - | 否 | null | 為IDR產品提供更精細化的控制,詳見ProductConfig。 | 參考請求樣本 |
ProductConfig欄位說明
欄位名稱 | 資料類型 | 最大長度 | 是否必填 | 預設值 | 描述 | 樣本值 |
pageInfoCheck | Array | - | 否 | null | 在證件防偽檢測中進行頁面資訊檢查,詳細檢查項,請參見證件防偽檢測組件。 說明:頁面資訊檢查僅適用於以下證件類型:
| [ {"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 | - | 否 | 不同的證件類型有不同的預設值:
| 已到期的證件是否可以通過驗證。取值:
說明:
| "N" |
cropFaceImageFromDoc | String | 1 | 否 | N | 是否從採集的證件圖片中裁剪出人臉圖片。取值如下:
| "Y" |
enableOCR | String | - | 否 | N | 是否開啟OCR功能。取值如下:
| "Y" |
spoofMode | String | 10 | 否 | CLOSED | 證件防偽等級。取值如下:
| "STANDARD" |
deeperMode | String | 10 | 否 | CLOSED | AIGC攻擊檢測的Deeper等級,Deeper檢測功能的詳細介紹,請參見什麼是Deeper。該參數支援以下取值:
注意:需要先購買Deeper產品,才能使用該功能。 | "STANDARD" |
ConsistencyCheckItem類型說明
commonConsistencyCheck
欄位名稱 | 資料類型 | 取值範圍 | 描述 | 支援的證件 / 國家或地區 / 證件類型 | OCR一致性檢查支援欄位 |
type | String | commonConsistencyCheck | 對證件防偽檢測中的OCR欄位進行一致性檢查。 | 大馬卡 / 馬來西亞 / 00600000001 |
|
mrzVisualConsistencyCheck
欄位名稱 | 資料類型 | 取值範圍 | 描述 | 支援的證件 / 國家或地區 / 證件類型 | OCR一致性檢查支援欄位 |
type | String | mrzVisualConsistencyCheck | 對證件防偽檢測中機讀區和視讀區的OCR欄位進行一致性檢查。 | - | - |
details | List<String> | 在
| MyVisa / 馬來西亞 / 00600000011 |
| |
護照(含機讀區和視讀區)/ 所有國家或地區 / 00000001006 |
| ||||
往來港澳通行證 / 中國大陸 / 00860000011 |
|
passportCountryCheck
欄位名稱 | 資料類型 | 取值範圍 | 描述 | 支援的證件 / 國家或地區 / 證件類型 / OCR一致性檢查支援欄位 / 預設國家代碼 |
type | String | passportCountryCheck | 檢查OCR結果中的 | - |
valueRange | List<String> | 應與預設國家代碼一致 | OCR結果中的 當 | 以下證件的
|
每一項都應符合ISO_3166-1_alpha-3標準 | 以下證件的
|
返回參數
欄位名稱 | 資料類型 | 必須返回 | 描述 | 樣本值 |
result | 是 | API請求結果,包含結果狀態、結果碼和結果訊息。 | { "resultCode": "PROCESSING", "resultStatus": "S", "resultMessage": "It is still under processing" } | |
transactionId | String | 是 | 事務ID。 說明:僅當交易進入處理階段後系統才會返回
| "G000000005FID2020030400000000000157****" |
Result欄位說明
欄位名稱 | 資料類型 | 必須返回 | 描述 | 樣本值 |
resultCode | String | 是 | 結果碼。
| "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"
}
}