金润·高速通-高速里程同车型排比接口文档
目录
1. 接口描述
接口名称 |
高速通-高速里程同车型排比 |
接口编号 |
JR-GST-005 |
接口描述 |
指定车辆指定时期（以月为单位）的通行里程排名信息(按车型） |
接口地址 |
/dmp/api |
请求方式 |
POST |
加密方式 |
RSA2 |
注意事项：
当返回码“为20001”时， 需要调用“上传授权委托书接口”先上传授权委托书，上传成功之后，重新调用本接口。
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&sig |
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 公共请求参数
参数 |
类型 |
必填 |
最大长度 |
说明 |
String |
Y |
32 |
金润商务提供 |
|
method |
String |
Y |
100 |
固定值： "jinrun.highway.car.mileage.compare" |
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 接口请求参数
参数 |
类型 |
必填 |
最大长度 |
说明 |
|
biz_content
|
plateColor |
Integer |
Y |
2 |
车牌颜色 0-蓝色，1-黄色， 2-黑色，3-白色， 4- 渐变绿色 5- 黄绿双拼色 6- 蓝白渐变色 7- 临时牌照 11-绿色 12-红色 |
plateNum |
String |
Y |
10 |
车牌号 |
|
name |
String |
Y |
18 |
个人姓名/企业名称 |
|
tel |
String |
N |
18 |
手机号/经办人手机号 |
|
idNum |
String |
Y |
30 |
身份证号/企业证件号 |
|
agentName |
String |
N |
50 |
经办人姓名 |
|
agentIdNum |
String |
N |
50 |
经办人身份证号 |
|
startDate |
String |
Y |
10 |
yyyy-MM-dd 当单位为月时，开始时间必须为单位月份的第一天 |
|
endDate |
String |
Y |
10 |
yyyy-MM-dd 当单位为月时，结束时间必须为单位月份的最后一天 |
|
serialNo |
String |
Y |
50 |
流水号 |
|
userCode |
String |
Y |
50 |
授权UserCode，参考授权接口文档 |
|
提示：姓名/手机号/身份证号不可都为空
单月查询（多月查询报错返回：查询范围最大只能为1个月！）
4. 响应参数
4.1 公共响应参数
参数 |
类型 |
说明 |
code |
String |
响应码参见附录6 |
request_id |
String |
请求Id |
message |
String |
响应信息 |
timestamp |
Long |
时间戳 |
data |
String |
返回数据 |
4.2 接口响应参数
参数 |
类型 |
说明 |
ranking |
Double |
排名 确定时间段内有多少同车型车辆的通行里程小于指定车辆的通行里程/指定时间段内同车型所有车辆数*100% |
ringRatio |
Double |
环比 按照上述方式计算上一个时间段的排名，两者差值 |
yearOveryear |
Double |
同比 按照上述方式计算去年同一时期的排名，两者差值 |
serialNo |
String |
流水号 |
5. 代码示例
5.1 请求示例
biz_content的json格式样例
{ "agentIdNum": "", "agentName": "", "userCode":"xxx", "endDate": "2021-09-30", "idNum": "43290119790409xxxx", "name": "唐xx", "plateColor": 1, "plateNum": "湘DB3652", "serialNo": "111", "startDate": "2021-09-01", "tel": "" } |
5.2 响应示例
{ "request_id": "SN1534405129980219392", "code": "00000", "data": { "ringRatio": 10, "serialNo": "55ac9936-a625-4059-af19-9f162329b10a", "ranking": 15, "yearOveryear": 11 }, "message": "操作成功", "timestamp": 1654665665622 } |
5.3 异常示例
6. 附录
6.1 接口返回码
编码 |
描述 |
是否收费 |
00000 |
查询成功 |
收费 |
20001 |
需要先调用上传授权书接口 |
免费 |
400 |
服务器不理解请求的语法。 |
免费 |
401 |
请求要求身份验证。 |
免费 |
403 |
服务器拒绝请求。 |
免费 |
404 |
服务器找不到请求的网页。 |
免费 |
405 |
禁用请求中指定的方法。 |
免费 |
406 |
无法使用请求的内容特性响应请求的网页。 |
免费 |
407 |
请求要求身份验证。 |
免费 |
408 |
服务器等候请求时发生超时。 |
免费 |
409 |
服务器在完成请求时发生冲突。 |
免费 |
410 |
如果请求的资源已永久删除，服务器就会返回此响应。 |
免费 |
411 |
服务器不接受不含有效内容长度标头字段的请求。 |
免费 |
412 |
服务器未满足请求者在请求中设置的其中一个前提条件。 |
免费 |
413 |
服务器无法处理请求，因为请求实体过大，超出服务器的处理能力。 |
免费 |
414 |
请求的 URI（通常为网址）过长，服务器无法处理。 |
免费 |
415 |
请求的格式不受请求页面的支持。 |
免费 |
416 |
如果页面无法提供请求的范围，则服务器会返回此状态代码。 |
免费 |
417 |
服务器未满足期望请求标头字段的要求。 |
免费 |
500 |
服务器遇到错误，无法完成请求。 |
免费 |
501 |
服务器不具备完成请求的功能。 |
免费 |
502 |
服务器作为网关或代理，从上游服务器收到无效响应。 |
免费 |
503 |
服务器目前无法使用（由于超载或停机维护）。 |
免费 |
504 |
服务器作为网关或代理，但是没有及时从上游服务器收到请求。 |
免费 |
505 |
服务器不支持请求中所用的 HTTP 协议版本。 |
免费 |
703 |
参数非法或者为空。 |
免费 |
704 |
业务查询失败。 |
免费 |
711 |
无数据。 |
免费 |
716 |
响应失败。 |
免费 |
949 |
协议中未定义此类文件名（协议调用错误，文件名不正确）。 |
免费 |
950 |
鉴权失败。 |
免费 |
951 |
文件md5校验失败。 |
免费 |
999 |
未知错误。 |
免费 |
