recognize

2022-05-09 03:03

概览

API 名称：ZOLOZ SaaS ID Recognition API

API URL：/api/v1/zoloz/idrecognition/recognize

API 描述：为大部分证件，如护照、身份证、驾照等提供文字识别（Optical Character Recognition，简称 OCR）功能，以及证件反欺诈结果。

版本

日期	版本	发布说明
2019.11.25	1.0.0	首次发布
2019.11.28	1.0.1	更新 API 内容
2019.11.29	1.0.2	更新 OCR 信息
2021.12.23	1.0.3	更新图片大小限制

请求

字段说明

字段名称	类型	最大长度	是否必填	取值范围	描述	示例值
bizId	string	32B	是	不能为 null 或空字符串	出于追踪目的的业务 ID	"trans-abc-1234"
docType	string	32B	是	不能为 null 或空字符串	证件类型，请参见支持的证件类型和返回的 OCR 结果。	"00000001003"
frontPageImage	string	5MB	是	不能为 null 或空字符串	证件的正面照，支持 base64 编码的 jpg 格式。	"/9j/4AA..[omitted]..PxA="
backPageImage	string	5MB	否		证件的背面照，支持 base64 编码的 jpg 格式。	"/9j/4AA..[omitted]..PxA="

请求示例

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

{
  "bizId": "trans-test-1234",
  "docType": "00000001003",
  "frontPageImage": "/9j/4AA..[omitted]..PxA=",
  "backPageImage": "/9j/4AA..[omitted]..PxA="
}

响应

字段说明

字段名称	类型	是否必填	取值范围	描述	示例值
transactionId	string	否		事务 ID	"G000000005FID20200304000000000001570702"
recognitionResult	string	否	"Y" "N"	识别结果	"Y"
recognitionErrorCode	string	否	NO_REQUIRED_ID BLUR NO_FACE_DETECTED NOT_REAL_DOC EXPOSURE UNKNOWN	识别错误码	"BLUR"
ocrResult	Map	否		OCR结果，更多信息请参见附录。
spoofResult	Map	否		反欺诈结果，更多信息请参见附录。
result	CommonResult	是		通用结果，更多信息请参见附录。

响应示例

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

{
  "transactionId": "G000000005FID20200304000000000001570702",
  "recognitionResult": "Y",
  "ocrResult": {
        "ID_NUMBER": "xxxx",
        "COUNTRY": "xxxxx",
        "SEX": "M",
        "LAST_NAME": "xxxxx",
        "DATE_OF_BIRTH": "xxxxx",
        "FIRST_NAME": "xxxxx"
    },
  "spoofResult": {
        "TAMPER_CHECK": "Y",
        "MATERIAL_CHECK": "Y",
        "SCREEN_RECAPTURE_CHECK": "Y"
    },
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  }
}

附录

CommonResult Model

描述：标识 API 调用状态的统一数据结构。

字段说明

字段名称	类型	是否必填	取值范围	描述	示例值
resultCode	string	是		结果码	"SUCCESS"
resultStatus	string	是	"S"：成功 "F"：失败	结果状态	"S"
resultMessage	string	是		结果描述	"success"

resultCode 在业务层面的取值范围：

resultCode	Description
SUCCESS	成功
SYSTEM_ERROR	其他内部错误
INVALID_ARGUMENT	输入参数无效

Spoof Result

关于欺诈结果值的进一步说明：

字段名称	类型	是否必填	取值范围	描述	示例值
TAMPER_CHECK	string	是	"Y"：未被篡改 "N": 被篡改	检测 ID 证件是否被篡改过。	"Y"
MATERIAL_CHECK	string	是	"Y"：材料正确 "N"：材料不正确	检查ID 证件的材料是否正确，如果 ID 是黑白材料，将返回 N。	"Y"
SCREEN_RECAPTURE_CHECK	string	是	"Y"：不是从屏幕中重新捕获的 "N"：从屏幕中重新捕获的	检查是否是从屏幕上重新捕获的 ID	"Y"