人像比对V2-001042100
<p>[TOC]</p>
<h5>1.<strong>使用说明</strong></h5>
<p>1.1 数据格式
服务请求采用HTTPS协议，用户需以HTTPS POST方式传输给服务端；传输参数的报文串以JSON数据串传输，编码格式为UTF-8；请严格依照参数规范设置参数，切勿遗漏“必填”参数，注意大小写区分
1.2 服务访问地址
测试环境: <a href="https://[ip地址或主机名]:[端口号]/api/v1/app/test/authservice">https://[ip地址或主机名]:[端口号]/api/v1/app/test/authservice</a>
生产环境: <a href="https://[ip地址或主机名]:[端口号]/api/v1/app/authservice">https://[ip地址或主机名]:[端口号]/api/v1/app/authservice</a>
所有服务访问相同的的地址。
1.3 消息体定义
请求消息的格式样例如下：</p>
<pre><code>{
"meta": {
"account": "XXX",
"service_code": "001000000",
"request_sn": "48982789438392929",
"timestamp": 1535622793245,
"sign": "64cd46e5f879232389003e5564c6e44e"
},
"params": {
"name": "XXX",
"id_no": "XXX"
}
}</code></pre>
<p>请求消息体分为两部份，meta内是认证和服务号参数，params内是服务号对应的输入参数，输入参数需根据相应的服务类型设置。
请求参数说明如下：</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>是否必填</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>account</td>
<td>String</td>
<td>必填</td>
<td>账号名</td>
</tr>
<tr>
<td>service_code</td>
<td>String</td>
<td>必填</td>
<td>服务号编码，每个服务类对应一个编码</td>
</tr>
<tr>
<td>timestamp</td>
<td>Long</td>
<td>必填</td>
<td>时间戳</td>
</tr>
<tr>
<td>request_sn</td>
<td>String</td>
<td>必填</td>
<td>调用方生成的唯一请求流水号，不超过40位</td>
</tr>
<tr>
<td>timestamp</td>
<td>Long</td>
<td>必填</td>
<td>请求签名，具体签名规则详见1.4节</td>
</tr>
</tbody>
</table>
<p>响应消息体也分为两部份，meta内是响应结果和相关元数据，data内是返回的数据，不同的服务类型的返回数据请参照相关服务的接口章节。
返回消息的格式样例如下：</p>
<pre><code>{
"meta": {
"service_code": "001040100",
"result_code": "200",
"result_desc": "查询成功"
},
"data": {
"result": "XXX",
"name": "XXX",
"id_no": "XXX",
"birthday": "XXX",
"gender": "XXX"
}
}</code></pre>
<p>返回数据说明如下：</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>是否必填</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>service_code</td>
<td>String</td>
<td>必填</td>
<td>服务号编码，每个服务类对应一个编码</td>
</tr>
<tr>
<td>result_code</td>
<td>String</td>
<td>必填</td>
<td>返回结果码，详情请参照下表</td>
</tr>
<tr>
<td>result_desc</td>
<td>Long</td>
<td>必填</td>
<td>返回结果描述</td>
</tr>
</tbody>
</table>
<p>返回码的定义如下：</p>
<table>
<thead>
<tr>
<th>返回码</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>查询成功</td>
</tr>
<tr>
<td>204</td>
<td>查询成功且无内容</td>
</tr>
<tr>
<td>400</td>
<td>输入参数错误</td>
</tr>
<tr>
<td>401</td>
<td>未授权账户</td>
</tr>
<tr>
<td>402</td>
<td>系统该服务已达每日调用上限</td>
</tr>
<tr>
<td>403</td>
<td>该账户此服务已达每日调用上限</td>
</tr>
<tr>
<td>404</td>
<td>服务不支持</td>
</tr>
<tr>
<td>407</td>
<td>IP地址受限</td>
</tr>
<tr>
<td>408</td>
<td>签名错误</td>
</tr>
<tr>
<td>409</td>
<td>请求超时</td>
</tr>
<tr>
<td>500</td>
<td>内部执行异常</td>
</tr>
<tr>
<td>504</td>
<td>数据查询异常</td>
</tr>
</tbody>
</table>
<p>1.4 签名算法</p>
<ul>
<li>
<p>为了保证传输数据的真实性与有效性，调用方需对请求数据签名，我方在接收请求后会进 行签名校验，校验失败将拒绝请求。
签名过程主要分为两个步骤：
1)生成需要签名的原始字符串；
2)使用摘要算法计算原始字符摘要信息作为签名；</p>
</li>
<li>a)签名原始字符串
签名原始字符串 = 账号 + 请求流水号 + 服务号 + 时间戳 + 密码
假设已知请求参数如下：
String account= "testsign";
String request_sn = "48982789438392929";
String service_code= "001001000";
Long timestamp = 1535622793245;
String password= "3GepGpfcvPaVtNKuaCy1";
则签名原始字符串为:
String signStr = account+ request_sn+ service_code+ timestamp +password;
计算结果即：
testsign4898278943839292900100100015356227932453GepGpfcvPaVtNKuaCy1</li>
<li>b)签名计算
原始字符串生成好之后需要计算其摘要信息作为签名，使用MD5算法</li>
<li>c)生成的原始字符串的签名计算方法为：
String signature = md5(signStr)
计算结果signature则为签名。
签名为:cb6cc0fb2fa6dc97f5b4d18b9ad53b6f</li>
</ul>
<h5>2.<strong>安全策略</strong></h5>
<p>数据传输采用HTTPS的TLS/SSL方式加密解密，客户端请求服务时会从服务端获取服务端的公钥，然后客户端使用服务端公钥加密数据发送给服务端，服务端收到加密数据后，使用服务端的私钥解密数据和处理请求。考虑到服务端的证书有可能是self sign的，所以客户端在收到服务端公钥时不对该公钥做验证；</p>
<h5>3.<strong>测试信息</strong></h5>
<p>测试接口对接时需要知道服务器访问地址，账号和密码，请与中新金科联系开通账号。</p>
<h5>4.<strong>接口规范：（服务号001042100）</strong></h5>
<p>4.1 说明
验证公民人像一致性接口
4.2 请求消息样例</p>
<pre><code>{
"meta": {
"account": "xxx",
"service_code": " 001042100",
"request_sn": "48982789438392929",
"timestamp": 1535622793245,
"sign": "64cd46e5f879232389003e5564c6e44e"
},
"params": {
"name": "XXX",
"id_no": "XXX",
"photo": "/9j/4AAQSkZJRgABAgAAAQABAAD//gAKSFMwMQGqAQSNBgB8igD/2wBDA A0JCgwKCA0MCwwPDg0QFCEWFBISFCkdHxghMCoyMi8qLi41PExBNThIOS4uQlp DSE9RVVZVM0BdZF1TY0xUhjVV9T0/wCHTE6PcDOVExwPTgf/AFq66uF8M2N1Y 6PAZpZraKUF96ZI9sgHjtXRQ6XBdxiRryhvRLC6okWYXrWoS6nqMjSMQEGFH06/n Wc+Q/FFFdUdjnk9R6YIIOcYJ/Q1EjkH6UUVTJP/9k=",
"request_sn": "48982789438392929"
}
}</code></pre>
<p>4.3 请求参数说明</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>是否必填</th>
<th>说明</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>String</td>
<td>必填</td>
<td>公民姓名</td>
<td></td>
</tr>
<tr>
<td>id_no</td>
<td>String</td>
<td>必填</td>
<td>公民身份证</td>
<td></td>
</tr>
<tr>
<td>photo</td>
<td>String</td>
<td>必填</td>
<td>公民高清照片，格式为 BASE64</td>
<td>大小小于1M</td>
</tr>
<tr>
<td>is_encrypt</td>
<td>String</td>
<td>选填</td>
<td>公民身份证是否AES加密</td>
<td>0否/1是，默认不加密</td>
</tr>
<tr>
<td>request_sn</td>
<td>String</td>
<td>选填</td>
<td>调用方请求流水号，非空时返回信息中会包含流水号信息</td>
<td>不超过40位</td>
</tr>
</tbody>
</table>
<p>4.4 同步返回消息样例
返回消息样例格式如下:</p>
<pre><code>{
"meta": {
"service_code": "001042100",
"result_code": "200",
"result_desc": "查询成功"
},
"data": {
"request_sn": "48982789438392929",
"res_code": 200,
"id_no_result": "一致",
"name_result": "一致",
"photo_result": "系统判断为不同人",
"photo_score": "9",
"error_message": "上传相片质量校验不合格，请重新拍摄上传",
"citizen_result": 2000,
"face_result": 2000
}
}</code></pre>
<p>4.5 返回参数说明</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>是否必填</th>
<th>说明</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>res_code</td>
<td>int</td>
<td>必填</td>
<td>查询结果: 200-查询成功 400-查询失败，原因见error_message</td>
<td></td>
</tr>
<tr>
<td>request_sn</td>
<td>String</td>
<td>选填</td>
<td>调用方传入的请求流水号</td>
<td></td>
</tr>
<tr>
<td>id_no_result</td>
<td>String</td>
<td>必填</td>
<td>公民身份证认证结果 一致；不一致；</td>
<td>只有在查询成功时候返回结果</td>
</tr>
<tr>
<td>name_result</td>
<td>String</td>
<td>必填</td>
<td>公民姓名认证结果 一致；不一致</td>
<td>只有在查询成功时候返回结果</td>
</tr>
<tr>
<td>photo_result</td>
<td>String</td>
<td>必填</td>
<td>照片对比结果: 详见附录5.2说明</td>
<td>只有在查询成功时候返回结果</td>
</tr>
<tr>
<td>photo_score</td>
<td>String</td>
<td>必填</td>
<td>照片相似的分数(0-100)</td>
<td>只有在查询成功时候返回结果</td>
</tr>
<tr>
<td>error_message</td>
<td>String</td>
<td>选填</td>
<td>错误信息：库中无此号，请到户籍所在地进行核实；上传相片质量校验不合格，请重新拍摄上传；相片文件不能大于1m</td>
<td></td>
</tr>
<tr>
<td>citizen_resul</td>
<td>int</td>
<td>必填</td>
<td>身份核验结果</td>
<td>只有在查询成功时候返回结果</td>
</tr>
<tr>
<td>face_result</td>
<td>int</td>
<td>必填</td>
<td>人像对比结果</td>
<td>身份核验通过时，结果参照返回码描述。身份核验未通过时，结果为1000.</td>
</tr>
</tbody>
</table>
<h5>5.<strong>附录</strong></h5>
<p>5.1 身份核验结果码的说明如下：</p>
<table>
<thead>
<tr>
<th>返回码</th>
<th>说明</th>
<th>备注</th>
<th>是否收费</th>
</tr>
</thead>
<tbody>
<tr>
<td>2000</td>
<td>一致</td>
<td>验证一致</td>
<td>是</td>
</tr>
<tr>
<td>2001</td>
<td>不一致</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>2002</td>
<td>库中无此号</td>
<td>身份证信息不存在</td>
<td>否</td>
</tr>
</tbody>
</table>
<p>5.2 人像对比结果码的说明如下：</p>
<table>
<thead>
<tr>
<th>返回码</th>
<th>说明</th>
<th>备注</th>
<th>是否收费</th>
</tr>
</thead>
<tbody>
<tr>
<td>1000</td>
<td>身份核验未通过</td>
<td>身份核验未通过</td>
<td>依据身份核验结果</td>
</tr>
<tr>
<td>2000</td>
<td>系统判断为同一人</td>
<td>验证一致</td>
<td>是</td>
</tr>
<tr>
<td>2001</td>
<td>系统判断为不同人</td>
<td>验证不一致</td>
<td>是</td>
</tr>
<tr>
<td>2002</td>
<td>不能确定是否为同一人</td>
<td>无法准确验证</td>
<td>是</td>
</tr>
<tr>
<td>2003</td>
<td>系统无法对比</td>
<td>无法验证</td>
<td>是</td>
</tr>
<tr>
<td>2004</td>
<td>库中无照片</td>
<td>照片信息不存在</td>
<td>是</td>
</tr>
</tbody>
</table>