接口描述
提供基于权威库的实名认证服务，支持二代居民身份证的三要素（姓名、身份号码+人像正脸照片）核验。
请求方法
POST
接口要求
- 图片格式限制：支持 jpeg格式，BASE64 字符串无需包含格式头，注意去除换行符
- 图片大小限制：原始尺寸需压缩至 10~40KB，否则可能会因为过小或过大而导致人像比对不通，影响比对效率；
请求URI
/v1/aiop/api/348c0ca2pkw0/gcapi/simpauth66
请求参数
1.请求头header参数
| 参数 |
是否必填 |
参数类型 |
说明 |
示例 |
下级对象 |
| Content-Type |
是 |
String |
json 格式 |
application/json |
|
| appkey |
是 |
String |
平台应用appkey |
562b89493b1a40e1b97ea05e50dd8170 |
|
| ctyun-eop-request-id |
是 |
String |
用户请求 id，由用户构造，用户可以通过 uuid 等方法自行生成唯一字符串，用于日志请求追踪。
详见文档：Python3调用示例 |
33dfa732-b27b-464f-b15a-21ed6845afd5 |
|
| eop-date |
是 |
String |
请求时间，由用户构造，形如 yyyymmddTHHMMSSZ。
详见文档：Python3调用示例 |
20211221T163014Z |
|
| host |
是 |
String |
终端节点域名，固定字段 |
ai-global.ctapi.ctyun.cn |
|
| Eop-Authorization |
是 |
String |
由天翼云官网 accessKey 和 securityKey 经签名后生成，参与签名生成的字段包括天翼云官网 accessKey 、securityKey、平台应用的appkey（非必须），用户请求id（非必须），请求时间，终端节点域名（非必须）以及请求体内容。
签名逻辑详见文档：认证鉴权和Python3调用示例 |
|
|
2.请求体body参数
| 参数 |
是否必填 |
参数类型 |
说明 |
示例 |
下级对象 |
| portrait |
是 |
String |
BASE64 编码的人像图;原始尺寸需压缩至 10~40KB，否则可能会因为过小或过大而导致人像比对不通，影响比对效率； BASE64 字符串无需包含格式头，注意去除换行符 |
|
"_9j_4AAQSkZJRgA..." |
| idNum |
是 |
String |
认证的用户身份证号码（号码最后一位 X 约定为大写） |
13x6xx199x07xx98xx |
|
| fullName |
是 |
String |
认证的用户姓名（注意去除空格等非常规字符） |
龙傲天 |
|
请求代码示例
Curl -X POST
"https://ai-global.ctapi.ctyun.cn/v1/aiop/api/348c0ca2pkw0/gcapi/simpauth66"
-H "Content-Type: application/json"
-H "ctyun-eop-request-id:33dfa732-b27b-464f-b15a-21ed6845afd5"
-H "appkey:XXX"
-H "Eop-Authorization:XXX"
-H "eop-date:20211109T104641Z"
-H "host:ai-global.ctapi.ctyun.cn"
--data '{"portrait": "_9j_4AAQSkZJRgA...","idNum": "13x6xx199x07xx98xx","fullName": "龙傲天"}'
返回值说明
1.请求成功返回响应参数
| 参数 |
是否必填 |
参数类型 |
说明 |
示例 |
下级对象 |
| statusCode |
是 |
Lnt |
返回状态，返回 0 表示成功，返回错误代码参考下面的错误代码列表。 |
0 |
|
| retMessage |
是 |
String |
接口调用结果/认证结果文字说明 |
"success" |
|
| certToken |
是 |
String |
本次认证的记录凭证，建议记录起来，方便后续定位排查，当code为0、4101、4109时，该字段不为空 |
|
|
| resStr |
是 |
String |
本次认证结果的具体说明，详看“认证结果代码说明”；若仅判断认证是否成功，可直接通过code判断，当code为0、4101、4109时，该字段不为空 |
|
|
认证结果代码说明
| 结果字节 |
所表示的结果 |
| 第一字节 |
姓名，身份号码比对结果 |
| 第二字节 |
人像比对结果 |
| 第三字节 |
可忽略 |
| 第四字节 |
可忽略 |
第一字节说明
| 返回代码 |
代码说明 |
可能出现原因 |
下一步建议 |
| 0 |
身份信息有效 |
-- |
-- |
| 5 |
身份信息无效 |
1.身份信息不存在 2.身份信息不匹配 |
检查身份信息 |
| 6 |
参数错误 |
身份信息格式不正确 |
检查身份信息 |
| 7 |
系统错误 |
系统错误或服务异常 |
-- |
| A |
穿网调用超时 |
公安内部接口穿网调用超时 |
-- |
| E |
接口调用异常 |
公安内部接口接口调用异常 |
-- |
| T |
接口调用超时 |
公安内部接口接口调用超时 |
-- |
| X |
未执行 |
未执行 |
-- |
| 其他代码 |
其他 |
其他 |
-- |
第二字节说明
| 返回代码 |
代码说明 |
可能出现原因 |
下一步建议 |
| 0 |
同一人 |
-- |
-- |
| 1 |
非同一人 |
1.照片为本人，但是照片可能有角度、光线过暗、脸部区域有亮斑；2.照片为本人，但是该照片尺寸太小 |
1.重新拍照； 2.传入合格图片 |
| 2 |
疑似为本人 |
1.照片为本人，但是照片可能有角度、光线过暗、脸部区域有亮斑；2.照片为本人，但是该照片尺寸太小；3.两人长相类似 |
1.重新拍照；2.传入合格图片 |
| A |
数据库操作错误 |
人像比对数据库操作异常 |
-- |
| B |
人像比对异常 |
人像比对系统异常 |
-- |
| C |
参数错误 |
身份证号为空或长度不是 18 位 |
-- |
| D |
无人像信息 |
数据库中无该人像信息 |
检查该人身份信息是否正确 |
| E |
图像格式不正式 |
非JPEG格式图像 |
检查传入的图像数据是否为JPEG格式 |
| F |
待比对图像建模失败 |
1.照片可能有角度，光线过暗，脸部区域有亮斑，模糊；2.照片尺寸太小 |
1.重新拍照；2.传入合格图片 |
| G |
现场照片质量不合格 |
上传照片质量不合格 |
自检上传照片质量 |
| J |
现场照片小于5K字节 |
现场照片小于5K字节 |
检查图像原始大小（非BASE64编码）是否小于5K字节，重新拍照 |
| K |
公安制证照片质量不佳 |
库内照片质量不佳 |
系统人像信息异常或者未录入认证系统 |
| T |
人像引擎超时 |
人像服务所有比对引擎同时超时或一个引擎超时，另一个引擎故障 |
重试 |
| W |
系统其他错误 |
认证超时 |
重试 |
| X |
未执行 |
未执行 |
重试或者联系运维人员 |
| 其他代码 |
其他 |
其他 |
-- |
返回值示例
1.请求成功返回值示例
{
"certToken": "d182ca85-xxxx-xxxx-xxxx-868cb258ceab",
"resStr": "00XX",
"statusCode": 0,
"retMessage": "成功"
}
2.请求失败返回值示例
{
"statusCode": 1,
"retMessage": "接口调用失败"
"error":"AI_OP_4101"
}
状态码
错误码说明
| 错误码 |
错误信息 |
错误描述 |
| AI_OP_1 |
接口调用失败 |
接口调用失败 |
| AI_OP_2 |
服务器错误 |
服务器错误 |
| AI_OP_4002 |
参数错误，见retMessage |
如 portrait字段需为图片转换的base64字符串、portrait字段过长、不是有效的身份号码 等 |
| AI_OP_4010 |
认证接口并发已到上限 |
QPS达到上限 |
| AI_OP_4101 |
身份认证未通过 |
身份认证未通过 |
| AI_OP_4103 |
身份认证服务异常 |
身份认证服务异常 |
| AI_OP_4104 |
认证接口调用超时 |
认证接口调用超时 |
| AI_OP_4109 |
非库内人员 |
非库内人员，该人员身份信息未收录或姓名与身份证号不匹配 |
base64 编码规则：使用常规的 safe base64 编码方式
- python 中推荐使用
base64.urlsafe_b64encode() 函数进行编码。
- java 中推荐使用
BASE64.getUrlEncoder().encodeToString() 函数进行编码。
