企业工商精确三要素认证-002009100
<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>接口规范：（服务号002009100）</strong></h5>
<p>4.1 说明
企业工商精确三要素认证接口
4.2 请求消息样例</p>
<pre><code>{
"meta": {
"account": "xxx",
"service_code": " 002009100",
"request_sn": "48982789438392929",
"timestamp": 1535622793245,
"sign": "64cd46e5f879232389003e5564c6e44e"
},
"params": {
"ent_name": "XXX",
"legal_per_name": "XXX",
"credit_code": "911XXX"
}
}</code></pre>
<p>4.3 请求参数说明</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>是否必填</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>ent_name</td>
<td>String</td>
<td>必填</td>
<td>企业名称</td>
</tr>
<tr>
<td>legal_per_name</td>
<td>String</td>
<td>必填</td>
<td>法人姓名</td>
</tr>
<tr>
<td>credit_code</td>
<td>String</td>
<td>必填</td>
<td>社会统一信用代码</td>
</tr>
</tbody>
</table>
<p>4.4 同步返回消息样例
返回消息样例格式如下:</p>
<pre><code>{
"meta": {
"service_code": "002009100",
"result_code": "200",
"result_desc": "查询成功"
},
"data": {
"res_code": 200,
"res_desc": "查询成功",
"ent_name_match": "1",
"credit_code_match": "0",
"legal_per_name_match": "1",
}
}</code></pre>
<p>4.5 返回参数说明</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>是否必填</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>charge</td>
<td>Boolean</td>
<td>必填</td>
<td>收费标识:true收费/false</td>
</tr>
<tr>
<td>res_code</td>
<td>String</td>
<td>必填</td>
<td>认证结果码</td>
</tr>
<tr>
<td>res_desc</td>
<td>String</td>
<td>必填</td>
<td>认证结果</td>
</tr>
<tr>
<td>ent_name_match</td>
<td>String</td>
<td>选填</td>
<td>企业名称认证结果: -1:无法验证;0:不一致;1:一致</td>
</tr>
<tr>
<td>credit_code_match</td>
<td>String</td>
<td>选填</td>
<td>社会统一信用代码认证结果: -1:无法验证;0:不一致;1:一致</td>
</tr>
<tr>
<td>legal_per_name_match</td>
<td>String</td>
<td>选填</td>
<td>法人认证结果: -1:无法验证;0:不一致;1:一致</td>
</tr>
</tbody>
</table>
<p>认证结果码的说明如下：</p>
<table>
<thead>
<tr>
<th>返回码</th>
<th>说明</th>
<th>备注</th>
<th>是否收费</th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>查询成功</td>
<td>查询成功</td>
<td>是</td>
</tr>
<tr>
<td>204</td>
<td>查询成功且无内容</td>
<td>查询成功且无内容</td>
<td>否</td>
</tr>
</tbody>
</table>