recognize

2024-11-05 07:22

概览

API URL：/api/v1/zoloz/idrecognition/recognize
API 描述：该接口用于为护照、身份证、驾照等大部分证件提供文字识别（Optical Character Recognition，简称OCR）功能和证件防伪检测结果。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32B	是	-	业务ID，业务的唯一标识，用于追踪业务。	"trans-abc-1234"
docType	String	32B	否	null	证件类型。`docType`和`autoDocTypes`不能同时传入，需选择其中一个传入。支持的C类证件，请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。支持的B类证件，请参见ID Recognition支持的企业类证件和返回的OCR结果。	"00000001003"
autoDocTypes	List<String>	200	否	null	证件类型列表。`docType`和`autoDocTypes`不能同时传入，需选择其中一个传入。如果传入`autoDocTypes`，ZOLOZ将自动对上传的证件进行分类。说明：目前护照不支持自动分类。新加坡证件`00650000001`和`00650000002`将统一归类为`00650000002`。如果ZOLOZ无法对上传的证件进行分类或分类的证件类型不在`autoDocTypes`中，此时将返回`NO_REQUIRED_ID`。支持的证件类型，请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。	["08520000001","08520000002"]
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字段的值进行预脱敏，例如进行哈希处理。	"123456abcd"
extraImageControlList	List<String>	-	否	null	指定是否返回额外的图片。支持的图片类型如下： `CROPPED_FACE_FROM_DOC`：从证件图片中裁剪出脸部区域并返回。说明：仅当`frontPageImage`中传入的证件图片含有人脸且裁剪成功时，才会返回额外的图片；否则，`extraImages`将返回空字符串 ""。	[ "CROPPED_FACE_FROM_DOC" ]
productConfig	ProductConfig	-	否	null	为IDR产品提供更精细化的控制。详细信息，请参见ProductConfig。	{ "consistencyCheck": [ { "type": "commonConsistencyCheck" }, { "details": [ "NAME", "SEX" ], "type": "mrzVisualConsistencyCheck" } ] }

ProductConfig字段说明

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
pageInfoCheck	Array	-	否	null	在证件防伪检测中进行页面信息检查，详细检查项，请参见证件防伪检测组件。说明：页面信息检查仅适用于中国香港身份证。	[ {"name":"id"}, {"name":"symbol"}, {"name":"name"} ]
consistencyCheck	List<ConsistencyCheckItem>	-	否	null	是否进行一致性检查。一致性检查仅适用于部分证件的特定字段，详见ConsistencyCheckItem。	[ { "type": "commonConsistencyCheck" }, { "details": [ "NAME", "SEX" ], "type": "mrzVisualConsistencyCheck" } ]
allowExpiredDocument	String	-	否	不同的证件类型有不同的默认值： `Y`：除护照（docType=00000001003）外的所有证件 `N`：护照（docType=00000001003）	已过期的证件是否可以通过验证。取值： `Y`：已过期的证件可以通过验证。 `N`：已过期的证件不能通过验证。当检测到证件过期时，IDR流程会失败。说明：如果传入的值为空或无效，此时将使用默认取值。	"N"
cropFaceImageFromDoc	String	1	否	N	是否从采集的证件图片中裁剪出人脸图片。取值如下： `Y`：是 `N`：否	"Y"
enableOCR	String	-	否	N	是否开启OCR功能。取值如下： `Y`：开启 `N`：不开启	"Y"
spoofMode	String	10	否	CLOSED	证件防伪等级。取值如下： `CLOSED`：所有的防伪算法都未开启。该等级可用于测试场景，测试进程不受算法的影响。 `STANDARD`：推荐的标准等级。 `LOOSE`：预留等级，暂不支持使用。 `STRICT`：预留等级，暂不支持使用。	"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
details	List<String>	请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。		护照（含机读区和视读区）/ 中国大陆、中国香港、中国台湾、中国澳门、菲律宾、新加坡、马来西亚 / 00000001006	ID_NUMBER COUNTRY_CODE EXPIRY_DATE DATE_OF_BIRTH

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
valueRange	List<String>	每一项都应符合ISO_3166-1_alpha-3标准		以下证件的`valueRange`为列表，且每一项都应符合ISO_3166-1_alpha-3标准。国际护照（仅含机读区） / 00000001003 / COUNTRY_CODE 国际护照（含机读区和视读区）/ 00000001006 / COUNTRY_CODE

返回参数

字段名称	数据类型	必须返回	描述	示例值
certType	String	否	证件类型，当证件验证完成时才返回`certType`字段。	"00600000001"
docEdition	Integer	否	身份证件的版本。 `1`~`3`：身份证件的版本，详见RealID和ID Recognition支持的证件类型和返回的OCR结果。 `0`：无法对身份证件进行分类或证件类型错误。 `-1`：未知错误。	1
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultCode":"SUCCESS", "resultStatus":"S", "resultMessage":"success" }
transactionId	String	否	事务ID。	"G000000005FID20200304000000000001570702"
recognitionResult	String	否	证件识别总结果。 `Y`：证件识别成功。 `N`：证件识别失败。	"Y"
recognitionErrorCode	String	否	证件识别不通过明细。 `NO_REQUIRED_ID`：证件图片不符合指定的证件类型。 `BLUR`：证件图片模糊。 `NO_FACE_DETECTED`：未检测到证件上的人脸。 `NOT_REAL_DOC`：证件防伪检测不通过。 `EXPOSURE`：证件图片过度曝光。 `UNKNOWN`：其他错误。	"BLUR"
recognitionErrorDescription	String	否	证件识别失败的原因。	""
ocrResult	Map	否	OCR识别结果。详细信息，请参见RealID和ID Recognition支持的证件类型和返回的OCR结果。	{ "ID_NUMBER": "xxxx", "COUNTRY": "xxxxx", "SEX": "M", "LAST_NAME": "xxxxx", "DATE_OF_BIRTH": "xxxxx", "FIRST_NAME": "xxxxx" }
ocrResultDetail	Map<String, OcrResultDetail>	否	OCR识别结果详情，当在API请求中传入`mrzVisualConsistencyCheck`时才返回该字段。	参考返回示例
spoofResult	Map	否	证件防伪分项检测结果，包含篡改、材质和屏幕翻拍等检测结果。详细信息，请参见spoofResult。	{ "TAMPER_CHECK": "Y", "MATERIAL_CHECK": "Y", "SCREEN_RECAPTURE_CHECK": "Y" }
extraImages	Map<String,String>	否	在`extraImageControlList`中指定的额外需要返回的图片。 Key是在`extraImageControlList`中指定的值。 Value是以Base64编码的图片内容。如果未找到请求的图片，则该值为“”。	{ "CROPPED_FACE_FROM_DOC": "/9j/4AA..[omitted]..PxA=" }

Result字段说明

字段名称	数据类型	必须返回	描述	示例值
resultCode	String	是	结果码。 SUCCESS：成功。 SYSTEM_ERROR：其他内部错误。 INVALID_ARGUMENT：输入参数无效。	"SUCCESS"
resultStatus	String	是	结果状态。 S：成功 F：失败	"S"
resultMessage	String	是	结果描述。	"success"

spoofResult字段说明

字段名称	数据类型	必须返回	描述	示例值
TAMPER_CHECK	String	是	身份证件是否通过了篡改检测。 `Y`：通过，即检测结果为未被篡改。 `N`：不通过，即检测结果为被篡改。	"Y"
MATERIAL_CHECK	String	是	身份证件是否通过了材质检测。 `Y`：通过。 `N`：不通过，例如检测结果为黑白材质。	"Y"
SCREEN_RECAPTURE_CHECK	String	是	身份证件是否通过了屏幕翻拍检测。 `Y`：通过。 `N`：不通过，即上传的证件被检测为从屏幕上翻拍的证件。	"Y"

代码示例

请求示例

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",
  "autoDocTypes":["08520000001","08520000002"],
  "frontPageImage": "/9j/4AA..[omitted]..PxA=",
  "backPageImage": "/9j/4AA..[omitted]..PxA=",
  "extraImageControlList":[
      "CROPPED_FACE_FROM_DOC"
  ],
  "productConfig": {
    "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": "CLOSED",
  "sceneCode": "changePassword",
  "userId": "123456abcd"
}

返回示例

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",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  },
  "certType": "xxx",
  "docEdition": 1,
  "ocrResult": {
    "COUNTRY_CODE_IN_ISO": "Y",
    "LOCAL_NAME": "xxxx",
    "ID_NUMBER": "xxxx",
    "MAC_ID": "",
    "COUNTRY": "xxxx",
    "SEX": "M",
    "LAST_NAME": "xxxx",
    "HK_ID": "",
    "DATE_OF_BIRTH": "xxxx",
    "FIRST_NAME": "xxxx",
    "EXPIRY_DATE": "xxxx",
    "COUNTRY_CODE": "xxxx"
  },
  "ocrResultDetail": {
    "MRZ_MAC_ID": {
      "name": "MAC_ID",
      "source": "MRZ",
      "value": ""
    },
    "MRZ_COUNTRY_CODE_IN_ISO": {
      "name": "COUNTRY_CODE_IN_ISO",
      "source": "MRZ",
      "value": "Y"
    },
    "MRZ_ID_NUMBER": {
      "name": "ID_NUMBER",
      "source": "MRZ",
      "value": "xxxx"
    },
    "VISUAL_ID_NUMBER": {
      "name": "ID_NUMBER",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "MRZ_DATE_OF_BIRTH": {
      "name": "DATE_OF_BIRTH",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_COUNTRY_CODE": {
      "name": "COUNTRY_CODE",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_EXPIRY_DATE": {
      "name": "EXPIRY_DATE",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_FIRST_NAME": {
      "name": "FIRST_NAME",
      "source": "MRZ",
      "value": "xxxx"
    },
    "MRZ_HK_ID": {
      "name": "HK_ID",
      "source": "MRZ",
      "value": ""
    },
    "MRZ_SEX": {
      "name": "SEX",
      "source": "MRZ",
      "value": "M"
    },
    "VISUAL_LOCAL_NAME": {
      "name": "LOCAL_NAME",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "VISUAL_EXPIRY_DATE": {
      "name": "EXPIRY_DATE",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "MRZ_LAST_NAME": {
      "name": "LAST_NAME",
      "source": "MRZ",
      "value": "xxxx"
    },
    "VISUAL_COUNTRY_CODE": {
      "name": "COUNTRY_CODE",
      "source": "VISUAL",
      "value": "xxxx"
    },
    "MRZ_COUNTRY": {
      "name": "COUNTRY",
      "source": "MRZ",
      "value": "xxxx"
    }
  },
  "recognitionResult": "Y",
  "recognitionErrorCode": "BLUR",
  "recognitionErrorDescription": "xxxxx",
  "spoofResult": {
    "TAMPER_CHECK": "Y",
    "SECURITY_FEATURE_CHECK": "Y",
    "MATERIAL_CHECK": "Y",
    "INFORMATION_CHECK": "Y",
    "SCREEN_RECAPTURE_CHECK": "Y"
  },
  "extraImages": {
      "CROPPED_FACE_FROM_DOC": "/9j/4AA..[omitted]..PxA="
  }
}