# 身份证

版本 V1.0.0

# 1. 接口定义

# 1.1 接口

URL = http://ip:port/hex/ocrapi/idcardocr

其中 ip 为部署机器的 ip 地址，port 为对应服务器的端口

# 1.2 描述

身份证 OCR 支持身份证正反面全字段内容检测识别功能，包括姓名、性别、民族、出生日期、地址、身份证ID、签发机关和有效期限关键字段识别。支持多种类型证件有效性检测告警，包括身份证边框不完整告警、身份证复印件告警、身份证翻拍告警和身份证卡片内局部区域遮挡告警等功能。可以应用于各种身份证信息有效性校验场景，例如银行开户、用户注册等场景。

# 1.3 HTTP请求格式

# 1.3.1 请求参数

参数名称	必选	类型	可选值	默认值	参数描述
image	和url二选一	String			`图像base64编码后的字符串，图像需是JPG、PNG、BMP其中之一的格式`
url	和image二选一	String			`图片url地址，url与image两者填一个即可，同时赋值时，则以url指定的图像作为输入`
session_id	否	String			`用户自定义的唯一会话id`
card_type	否	Int32	0\1\2	2	`身份证图片类型，0-正面，1-反面 2-自动识别`
border_check_flag	否	Bool	false\true	false	`身份证遮挡检测开关，如果输入图片中的身份证卡片边框不完整则返回告警`
enable_reshoot	否	Bool	false\true	false	`翻拍检测开关，如果输入图片是翻拍图片则返回告警`
enable_detect_copy	否	Bool	false\true	false	`复印件检测开关，如果输入图片中的身份证卡片是复印件，则返回告警`
ret_image	否	Bool	false\true	true	`是否返回识别后的切图（切图是指精确剪裁对齐后的身份证正反面图片），使用base64加密后的字符串`
ret_warncode_flag	否	Bool	false\true	false	`是否返回单告警码（已废弃该选项，为了向下兼容而保留，建议使用多重告警码）`
enable_recognize_warn_code	否	Bool	false\true	false	`是否返回多重告警码`
enable_quality_value	否	Bool	false\true	false	`是否返回图片质量数值（图片质量分数是评价一个图片的模糊程度的标准）`
ret_portrait_flag	否	Bool	false\true	false	`是否返回人像照片（身份证图片数据中的人像照片）`
enable_multicard_det	否	Bool	false\true	true	`是否开启多卡证检测错误码返回`
enable_detect_ps	否	Bool	false\true	false	`PS检测开关，如果输入图片是PS图片则返回告警`

# 1.3.2 请求示例

{
 "image": 填写Base64编码后的图片数据,
 "session_id": 填写对应的session_id,
 "card_type":2,
 "border_check_flag":true,
 "enable_reshoot":true,
 "enable_detect_copy":true,
 "ret_image":false,
 "enable_recognize_warn_code":true,
 "enable_quality_value":true,
 "ret_portrait_flag":false,
 "enable_detect_ps": true,
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# 1.3.3 返回参数

参数	是否必然返回	类型	参数说明
errorcode	是	Int32	`错误码`
errormsg	是	string	`错误码消息`
session_id	否	string	`相应请求的session标识符，可用于结果查询`
warncode	否	Int32	`单告警码，是否返回由 ret_warncode_flag决定。已废弃，为了接口兼容性需求保留，建议使用多重告警接口`
warnmsg	否	String	`单告警码信息，是否返回由 ret_warncode_flag决定。已废弃，为了接口兼容性需求保留，建议使用多重告警接口`
recognize_warn_code	否	Array	`多重告警码，是否返回由enable_recognize_warn_code决定`
recognize_warn_msg	否	Array	`多重告警码信息，是否返回由enable_recognize_warn_code决定`
name	否	String	`证件姓名`
name_confidence_all	否	Array	`证件姓名置信度`
sex	否	String	`性别`
sex_confidence_all	否	Array	`性别置信度`
nation	否	String	`民族`
nation_confidence_all	否	Array	`民族置信度`
birth	否	String	`出生日期`
birth_confidence_all	否	Array	`出生日期置信度`
address	否	String	`地址`
address_confidence_all	否	Array	`地址置信度`
id	否	String	`身份证号`
id_confidence_all	否	Array	`身份证号置信度`
frontimage	否	String	`身份证正面照片数据，使用base64加密后的字符串，是否返回由ret_image决定`
valid_date	否	String	`证件的有效期`
valid_date_confidence_all	否	Array	`证件的有效期置信度`
authority	否	String	`发证机关`
authority_confidence_all	否	Array	`发证机关置信度`
backimage	否	String	`身份证反面照片，使用base64加密后的字符串，是否返回由ret_image决定`
card_type	是	Int32	`0-正面 1-反面`
portrait	否	String	`人像照片，使用base64加密后的字符串，是否返回由ret_portrait_flag决定`
quality_value	是	Int32	`图片参数目前用于评估输入图片模糊程度取值范围：0~100 100 - 对应图片清晰 0 - 对应图片模糊图片质量判断建议阈值：50`
warn_code	否	Int32	`告警码`
warn_code_conf	否	Float	`用于反馈边框遮挡告警分数取值范围：0.0～100.0 建议阈值：50.0 <50.0，无边框遮挡告警 ≥50.0，有边框遮挡告警`

# 1.3.4 返回示例

{
  "address_confidence_all": [99,99,100,99,99,99,99,99,99,99,99,99],
  "frontimage_confidence_all": [],
  "sex": "女",
  "nation_confidence_all": [99],
  "recognize_warn_code": [],
  "portrait": "/9j/4AAQSkZJRgABAQAAAQABAAD/",
  "authority_confidence_all": [],
  "name_confidence_all": [
    100
  ],
  "id": "610333199012223323",
  "backimage_confidence_all": [],
  "errorcode": 0,
  "recognize_warn_code_conf": [
    {
      "warn_code": -9101,
      "warn_code_conf": 28
    }
  ],
  "sex_confidence_all": [
    99
  ],
  "valid_date_confidence_all": [],
  "birth_confidence_all": [100,100,100,100,100,100,100,100,100,100],
  "nation": "汉",
  "frontimage": "/9j/4AAQSkZJRgABAQAAAQABAAD/l8gpdiccov91sZ/",
  "birth": "1990/12/22",
  "address": "浙江省海盐县武原街工人路",
  "watermask_confidence_all": [],
  "id_confidence_all": [100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100],
  "name": "艾米",
  "errormsg": "OK",
  "quality_value": 97,
  "recognize_warn_msg": ["WARN_IDCARD_COVER_CARD"],
  "card_type": 0,
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# 1.3.5 接口错误码说明

错误码	错误码消息	错误码说明
-5208	OCR_SERVER_INTERN_ERROR	`服务器内部错误，初始化失败`
-1102	SDK_IMAGE_DECODE_FAILED	`图片解码失败`
-1313	ERROR_PARAMETER_INVALID	`身份证卡片类型参数无效，不在合法参数范围内`
-5107	OCR_IDCARD_INVALID	`身份证反（国徽）面字段信息识别出错`
-5109	OCR_IMAGE_BLUR	图片模糊
-5108	OCR_IDCARD_ILLEGAL	身份证信息不合法（身份证号、姓名字段校验非法等）
-5110	OCR_NOT_AN_IDCARD	非第二代身份证，临时身份证会返回该错误码
-5111	OCR_IDCARD_PARAM_ERROR	卡片正反面参数与实际传入图片不匹配
-5103	OCR_RECOG_FAILED	识别失败
-5112	OCR_NOT_SIGLE_CARD	多卡证错误

# 1.3.6 接口告警码说明

告警码	告警码消息	告警码说明
-9106	WARN_IDCARD_PS_CARD	身份证PS告警
-9105	WARN_IDCARD_COVER_CARD	身份证框内遮挡告警
-9104	WARN_IDCARD_TEMP_CARD	临时身份证告警
-9103	WARN_IDCARD_RESHOOT_CARD	身份证翻拍告警
-9102	WARN_IDCARD_COPY_CARD	身份证复印件告警
-9101	WARN_IDCARD_CORNER_EXCEED	身份证边框不完整告警
-9100	WARN_IDCARD_INVALID_DATE	身份证有效日期不合法告警
-9107	WARN_REFLECT_CARD	身份证图片反光告警

← 银行卡户口本 →