行驶证三要素标准版
<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>接口规范：（服务号004015300）</strong></h5>
<p>4.1 说明
行驶证三要素标准版接口
4.2 请求消息样例</p>
<pre><code>{
"meta": {
"account": "xxx",
"service_code": " 004015300",
"request_sn": "48982789438392929",
"timestamp": 1535622793245,
"sign": "64cd46e5f879232389003e5564c6e44e"
},
"params": {
"car_number": "xxx",
"name": "xxx",
"car_type": "xxx",
"request_sn": "123456"
}
}</code></pre>
<p>4.3 请求参数说明</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>是否必填</th>
<th>说明</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>car_number</td>
<td>String</td>
<td>必填</td>
<td>车牌号</td>
<td></td>
</tr>
<tr>
<td>car_type</td>
<td>String</td>
<td>必填</td>
<td>号牌种类</td>
<td></td>
</tr>
<tr>
<td>name</td>
<td>String</td>
<td>必填</td>
<td>姓名</td>
<td></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": "004015300",
"result_code": "200",
"result_desc": "查询成功",
"charge": true,
"order_no": "1934540125539799040"
},
"data": {
"res_code": "0000",
"res_desc": "查询成功",
"request_sn": "1512689645",
"check_result": "00",
"body_color": "黑",
"type": "XXXX",
"plate": "XXX",
"plate_type": "52",
"vehicle_type": "小型轿车",
"engine_model": "XXXX",
"vin": "XXXX",
"jian_che_time": "",
"first_issue_date": "2020-07-10 00:00:00",
"validity_day_end": "",
"vehicle_status": "正常",
"passengers": "5",
"retirement_date": "2099-12-31 00:00:00",
"fuel_type": "O",
"cc": "1395",
"pps_date": "2020-05-09 00:00:00",
"max_journey": "110",
"shaft": "2",
"wheel_base": "2871",
"front_tread": "1584",
"rear_tread": "1570",
"cross_weight": "2190",
"curb_weight": "1730",
"load_weight": "0"
}
}</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>详见附录4.6</td>
</tr>
<tr>
<td>res_desc</td>
<td>String</td>
<td>必填</td>
<td>返回结果说明</td>
</tr>
<tr>
<td>request_sn</td>
<td>String</td>
<td>选填</td>
<td>调用方请求流水号</td>
</tr>
<tr>
<td>check_result</td>
<td>String</td>
<td>选填</td>
<td>详见附录4.7</td>
</tr>
<tr>
<td>order_no</td>
<td>String</td>
<td>必填</td>
<td>平台流水号</td>
</tr>
<tr>
<td>brand_name</td>
<td>String</td>
<td>选填</td>
<td>品牌名称</td>
</tr>
<tr>
<td>body_color</td>
<td>String</td>
<td>选填</td>
<td>详见附录5.2 车身颜色</td>
</tr>
<tr>
<td>type</td>
<td>String</td>
<td>选填</td>
<td>具体车型</td>
</tr>
<tr>
<td>plate</td>
<td>String</td>
<td>选填</td>
<td>车牌号</td>
</tr>
<tr>
<td>plate_type</td>
<td>String</td>
<td>选填</td>
<td>车牌类型</td>
</tr>
<tr>
<td>vehicle_type</td>
<td>String</td>
<td>选填</td>
<td>详见附录4.9 车辆类型</td>
</tr>
<tr>
<td>engine_model</td>
<td>String</td>
<td>选填</td>
<td>发动机型号</td>
</tr>
<tr>
<td>vin</td>
<td>String</td>
<td>选填</td>
<td>车架号</td>
</tr>
<tr>
<td>jian_che_time</td>
<td>String</td>
<td>选填</td>
<td>年检日期(非必返回)</td>
</tr>
<tr>
<td>first_issue_date</td>
<td>String</td>
<td>选填</td>
<td>初次登记日期</td>
</tr>
<tr>
<td>validity_day_end</td>
<td>String</td>
<td>选填</td>
<td>核验有效期止</td>
</tr>
<tr>
<td>vehicle_status</td>
<td>String</td>
<td>选填</td>
<td>详见附录5.0 车辆状态</td>
</tr>
<tr>
<td>passengers</td>
<td>String</td>
<td>选填</td>
<td>核定载客数</td>
</tr>
<tr>
<td>retirement_date</td>
<td>String</td>
<td>选填</td>
<td>强制报废日期</td>
</tr>
<tr>
<td>fuel_type</td>
<td>String</td>
<td>选填</td>
<td>详见附录5.3 燃油种类</td>
</tr>
<tr>
<td>cc</td>
<td>String</td>
<td>选填</td>
<td>排量</td>
</tr>
<tr>
<td>pss_date</td>
<td>String</td>
<td>选填</td>
<td>出厂日期</td>
</tr>
<tr>
<td>max_journey</td>
<td>String</td>
<td>选填</td>
<td>最大功率</td>
</tr>
<tr>
<td>shaft</td>
<td>String</td>
<td>选填</td>
<td>轴数</td>
</tr>
<tr>
<td>wheel_base</td>
<td>String</td>
<td>选填</td>
<td>轴距</td>
</tr>
<tr>
<td>front_tread</td>
<td>String</td>
<td>选填</td>
<td>前轮距</td>
</tr>
<tr>
<td>rear_tread</td>
<td>String</td>
<td>选填</td>
<td>后轮距</td>
</tr>
<tr>
<td>cross_weight</td>
<td>String</td>
<td>选填</td>
<td>总质量</td>
</tr>
<tr>
<td>curb_weight</td>
<td>String</td>
<td>选填</td>
<td>整备质量</td>
</tr>
<tr>
<td>load_weight</td>
<td>String</td>
<td>选填</td>
<td>核定载客量</td>
</tr>
<tr>
<td>properties</td>
<td>String</td>
<td>选填</td>
<td>详见附录5.1 使用性质</td>
</tr>
</tbody>
</table>
<p>4.6查询结果码说明如下：</p>
<table>
<thead>
<tr>
<th>返回码</th>
<th>说明</th>
<th>是否收费</th>
</tr>
</thead>
<tbody>
<tr>
<td>0000</td>
<td>查询成功</td>
<td>是</td>
</tr>
<tr>
<td>1000</td>
<td>查无</td>
<td>是</td>
</tr>
</tbody>
</table>
<p>4.7核验结果码说明如下：</p>
<table>
<thead>
<tr>
<th>返回码</th>
<th>说明</th>
<th>是否收费</th>
</tr>
</thead>
<tbody>
<tr>
<td>00</td>
<td>姓名一致</td>
<td>是</td>
</tr>
<tr>
<td>01</td>
<td>姓名不一致</td>
<td>是</td>
</tr>
</tbody>
</table>
<p>4.8号牌种类结果码说明如下：</p>
<table>
<thead>
<tr>
<th>代码</th>
<th>含义</th>
</tr>
</thead>
<tbody>
<tr>
<td>01</td>
<td>大型汽车</td>
</tr>
<tr>
<td>02</td>
<td>小型汽车</td>
</tr>
<tr>
<td>03</td>
<td>使馆汽车</td>
</tr>
<tr>
<td>04</td>
<td>领馆汽车</td>
</tr>
<tr>
<td>05</td>
<td>境外汽车</td>
</tr>
<tr>
<td>06</td>
<td>外籍汽车</td>
</tr>
<tr>
<td>07</td>
<td>普通摩托车</td>
</tr>
<tr>
<td>08</td>
<td>轻便摩托车</td>
</tr>
<tr>
<td>09</td>
<td>使馆摩托车</td>
</tr>
<tr>
<td>10</td>
<td>领馆摩托车</td>
</tr>
<tr>
<td>11</td>
<td>境外摩托车</td>
</tr>
<tr>
<td>12</td>
<td>外籍摩托车</td>
</tr>
<tr>
<td>13</td>
<td>低速车</td>
</tr>
<tr>
<td>14</td>
<td>拖拉机</td>
</tr>
<tr>
<td>15</td>
<td>挂车</td>
</tr>
<tr>
<td>16</td>
<td>教练汽车</td>
</tr>
<tr>
<td>17</td>
<td>教练摩托车</td>
</tr>
<tr>
<td>20</td>
<td>临时入境汽车</td>
</tr>
<tr>
<td>21</td>
<td>临时入境摩托车</td>
</tr>
<tr>
<td>22</td>
<td>临时行驶车</td>
</tr>
<tr>
<td>23</td>
<td>警用汽车</td>
</tr>
<tr>
<td>24</td>
<td>警用摩托</td>
</tr>
<tr>
<td>51</td>
<td>新能源大型车</td>
</tr>
<tr>
<td>52</td>
<td>新能源小型车</td>
</tr>
</tbody>
</table>