金润·核验通-身份证识别接口文档
身份证识别接口行业内常用语
身份证OCR识别-身份证图片识别-身份证识别-二代居民身份证OCR识别-身份证信息识别
目录
1. 身份证识别接口描述
接口名称 |
身份证识别 |
接口编号 |
JR-HYT-015 |
接口描述 |
用于进行识别身份证信息接口 |
接口地址 |
/dmp/api |
请求方式 |
POST |
加密方式 |
RSA2 |
2. 身份证识别接口加密方式
2.1 加签，验签机制说明
客户在应用中使用自己的“私钥”对消息加签之后，消息和签名会传递给金枢系统，金枢系统则使用应用的 公钥 验证消息的真实性（来自于合法应用的真实消息）。
对于金枢系统返回消息给商户应用的情形，应用则使用金枢系统的 公钥 来验证返回消息的真实性。
2.2 签名算法
签名算法：RSA2
标准签名算法：SHA256WithRSA
描述：强制要求 RSA 密钥的长度至少为 2048。
2.3 加密方式
请求体加密
将请求参数(biz_content)字段通过 私钥进行加密
2.4 生成签名
2.4.1 筛选并排序
获取所有请求参数（包括公共请求参数），不包括字节类型参数，如文件、字节流，剔除 sign 字段，剔除值为空的参数，并按照第一个字符的键值 ASCII 码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，以此类推。
2.4.2 拼接
将排序后的参数与其对应值，组合成 参数=参数值 的格式，并且把这些参数用 & 字符连接起来，此时生成的字符串为待签名字符串。
示例:
app_id=2014072300XXXXXX&biz_content=fV9IJsNcmZcPEQbvr8S3kkJ3uT0GRfHlAM25LT8w9xCAJqywxotrVlH1ZJsIXwHBvz97uFyNbBoSKbxfRgwKLl7P88hKBmPDwyDzB4t8MT&charset=UTF-8&method=alipay.trade.pay&sign_type=RSA2×tamp=2014-07-24 03:07:50&version=1.0
2.4.3 调用签名函数
使用各自语言对应的 SHA256WithRSA（对应 sign_type 为 RSA2）签名函数利用商户私钥对签名字符串进行签名，并进行 Base64 编码。把生成的签名 encode 后赋值给 sign 参数，拼接到请求参数中。
2.4.4 拼接完整请求
调用签名函数 后需将生成的签名作为 sign 的 value 拼接到请求数据中。
示例：
app_id=2014072300XXXXXX&biz_content=fV9IJsNcmZcPEQbvr8S3kkJ3uT0GRfHlAM25LT8w9xCAJqywxotrVlH1ZJsIXwHBvz97uFyNbBoSKbxfRgwKLl7P88hKBmPDwyDzB4t8MT&charset=UTF-8&method=alipay.trade.pay&sign_type=RSA2×tamp=2014-07-24 03:07:50&version=1.0&sign=GhT5Q6YxBtvf4q855TiNWEF/DIeLMyEE97+OnJDHpe6joNfr9F3BAE37dczcogU7uLfpNo+dh3cgly05bQN5nTj9TJ3SrBZWa40cltlgkI+6+0FuJoFSA225+MCrD4fNNqi2Zd5Adi9qC9NdN8nBVsjvzqtn5NepOt8dG1qdv7KvVwG74emFea1j2JuMBVBMp2PgIEwCv5c8OJSXa2P66+l3YCqEEMjBN22Dz0chlJ4hKMW3rA2oISH6ryzIvNIiy4/djKEdmxFeBorp1vrbmAtBqE++afggzzGt5w4arkbQ4fWLXJwkC9+1y4irCgmX65CEb5ct+fRgG2/9/B0rYg== |
2.5 解密方式
返回数据data内容是加密的，要用商户的公钥解密。
3. 身份证识别接口请求参数
3.1 公共请求参数
参数 |
类型 |
必填 |
最大长度 |
说明 |
app_id |
String |
Y |
32 |
金润商务提供 |
method |
String |
Y |
100 |
固定值： "jinrun.id.card.ocr" |
sign |
String |
Y |
|
参见2加密方式 |
charset |
String |
Y |
10 |
utf-8 |
format |
String |
Y |
10 |
json |
sign_type |
String |
Y |
10 |
RSA2 |
version |
String |
Y |
10 |
1.0 |
3.2 接口请求参数
参数 |
类型 |
必填 |
最大长度 |
说明 |
|
file |
File |
Y |
|
身份证图片 |
|
biz_content |
pageFlag |
String |
N |
1 |
文件页标记 0表示单页双面；1表示单页面；主要用于复印件识别;默认为1 |
doQuality |
String |
N |
1 |
是否进行质量评判 1表示执行，0表示不执行且后续所有质检属性字段无效，默认为1;跟是否识别doRec参数不能同时为0 |
|
judgedImag |
String |
N |
1 |
是否返回矫正平铺后的身份证图片 1表示返回，0表示不返回，且后续judgedImageWidth，judgedImageHeight，returnKeyPos无效;默认为0 |
|
judgedImageWidth |
String |
N |
1 |
矫正平铺后的图片宽度 默认为0，0表示使用原始宽度;doQuality为1时有效 |
|
judgedImageHeight |
String |
N |
1 |
矫正平铺后的图片高度 默认为0，0表示使用原始高度;doQuality为1时有效 |
|
illumination |
String |
N |
1 |
是否进行光照检测 1表示执行，0表示不执行。默认为1;doQuality为1时有效 |
|
definition |
String |
N |
1 |
是否进行清晰度检测 1表示执行，0表示不执行。默认为1;doQuality为1时有效 |
|
occlusion |
String |
N |
1 |
是否进行遮挡检测 1表示执行，0表示不执行;默认为1。doQuality为1时有效 |
|
hardCopy |
String |
N |
1 |
是否进行复印件检测 1表示执行，0表示不执行;默认为1。doQuality为1时有效 |
|
returnKeyPos |
String |
N |
1 |
是否在矫正平铺上的图上返回区域信息 1表示返回，0表示不返回;默认为0。doQuality为1时有效 |
|
doRec |
String |
N |
1 |
是否进行识别 1表示执行，0表示不执行且后续所有识别属性字段无效。默认为1 |
|
faceImage |
String |
N |
1 |
是否返回人脸图片 1表示返回，0表示不返回;默认为0。doRec为1时有效 |
|
4. 身份证识别接口响应参数
4.1 公共响应参数
参数 |
类型 |
说明 |
code |
String |
响应码，见附录6.1 |
request_id |
String |
请求Id |
message |
String |
响应信息 |
timestamp |
Long |
时间戳 |
data |
String |
返回数据 |
4.2 接口响应参数
参数 |
类型 |
说明 |
sessionId |
String |
sessionId |
statcode |
String |
状态码 |
state |
String |
识别内容（JSON字符串） |
4.3 字段说明
字段名称 |
中文描述 |
备注 |
name |
姓名 |
|
address |
住址 |
|
sex |
性别 |
|
nat |
民族 |
|
birth |
出生年月 |
|
number |
身份证号 |
|
validDate |
有效期限 |
|
issueUnit |
签发机关 |
|
isValid |
是否过期 |
0-已过期，1-未过期 |
idCardSide |
身份证正反面标记 |
0-未知，1-正面，-1-反面 |
faceImg |
身份证头像图片；base64编码格式 |
请求接口doRec和faceImage都上送为1返回 |
judgedImg |
矫正后图片；base64编码格式 |
请求接口doQuality和judgedImage都上送为1返回 |
qualityResultSummary |
质检整体效果 |
0-质量合格,-1-未进行质量评判,-2-缺边或缺角,-3-光照不合格,-4-清晰度不合格，模糊,-5-遮挡,-6-检测为复印件,-7-未检测到身份证区域 |
copiesCheck |
复印件检测结果 |
1表示原件，0表示未检测，-1表示复印件 |
definitionCheck |
清晰度检测结果 |
1表示清晰，0表示未检测，-1表示模糊 |
edgeAngleCheck |
边角检测结果 |
1表示边角完整，0表示未检测，-1表示缺边或缺角 |
illuminationCheck |
光照检测结果 |
1表示光照合格，0表示未检测，-1表示光照过亮或过暗 |
poorIlluminationField |
光照不合格区域信息 |
可能的区域值为name,sex, nation,birth,address,number, issueUnit,validDate,face |
occlusionCheck |
遮挡检测结果 |
1表示无遮挡，0表示未检测，-1表示存在文字或头像遮挡 |
poorOcclusionField |
遮挡区域信息 |
可能的区域值为name，sex, nation,birth,address,number, issueUnit,validDate,face |
validRegionCheck |
身份证有效性检测结果 |
1表示存在身份证，0表示未检测，-1表示非身份证图像 |
5. 身份证识别接口代码示例
5.1 请求示例
biz_content的json格式样例
{ "pageFlag":"1", "doQuality":"0" } |
5.2 响应示例
{ "request_id": "SN1594865659450363904", "code": "1700", "data": { "data": null, "resultInfoDTO": { "sessionId": "a42be9767221122092939666e7", "statcode": 1700, "state": "{\"nat\":\"汉\",\"address\":\"广州市越秀区越华路73号101房\",\"validRegionCheck\":\"1\",\"faceImg\":\"\",\"validDate\":\"\",\"definitionCheck\":\"1\",\"sex\":\"男\",\"birth\":\"1994年5月21日\",\"occlusionCheck\":\"1\",\"poorIlluminationField\":\"\",\"number\":\"44010419940521xxxx\",\"illuminationCheck\":\"1\",\"idCardSide\":\"1\",\"edgeAngleCheck\":\"1\",\"poorOcclusionField\":\"\",\"name\":\"林灝\",\"judgedImg\":\"\",\"copiesCheck\":\"1\",\"issueUnit\":\"\",\"qualityResultSummary\":\"0\"}" }, "sessionId": null, "resultInfo": "{\"sessionId\":\"a42be9767221122092939666e7\",\"statcode\":1700,\"state\":\"{\\\"nat\\\":\\\"汉\\\",\\\"address\\\":\\\"广州市越秀区越华路73号101房\\\",\\\"validRegionCheck\\\":\\\"1\\\",\\\"faceImg\\\":\\\"\\\",\\\"validDate\\\":\\\"\\\",\\\"definitionCheck\\\":\\\"1\\\",\\\"sex\\\":\\\"男\\\",\\\"birth\\\":\\\"1994年5月21日\\\",\\\"occlusionCheck\\\":\\\"1\\\",\\\"poorIlluminationField\\\":\\\"\\\",\\\"number\\\":\\\"44010419940521xxxx\\\",\\\"illuminationCheck\\\":\\\"1\\\",\\\"idCardSide\\\":\\\"1\\\",\\\"edgeAngleCheck\\\":\\\"1\\\",\\\"poorOcclusionField\\\":\\\"\\\",\\\"name\\\":\\\"林灝\\\",\\\"judgedImg\\\":\\\"\\\",\\\"copiesCheck\\\":\\\"1\\\",\\\"issueUnit\\\":\\\"\\\",\\\"qualityResultSummary\\\":\\\"0\\\"}\"}", "statcode": null, "state": null, "queryInfo": null }, "timestamp": 1669080587311 } |
5.3 异常示例
{ "request_id":"SN1526464148450447360", "code":"1790", "data":{ "resultInfoDTO":{ "sessionId":"a454b4e2962205171526293f8a4", "statcode":1790, "state":"" } }, "message":"", "timestamp":1652772394628 } } |
6. 身份证识别接口附录
6.1 接口返回码
编码 |
描述 |
是否收费 |
1700 |
识别成功 |
收费 |
998 |
参数异常 |
免费 |
400 |
异常信息 |
免费 |
1790 |
比对错误 |
免费 |
1910 |
无效参数 |
免费 |
2022 |
非法参数 |
免费 |
9100 |
账户无费用 |
免费 |
9110 |
账户无权限 |
免费 |
9200 |
账户错误 |
免费 |
9202 |
无效IP |
免费 |
9304 |
URL错误 |
免费 |
