`                                                           

1 引言

1.1 文档概述

为落实对进站原料运输车辆的日常监管责任，要求所有进站原料运输车辆数据上传到支队“城市工程运输车综合治理系统”。为统一各数据接入制定本标准，各企业根据该文档，要求厂家将数据接入到支队监管平台中。

1.2 阅读对象

a.闸机设备厂家，数据接入的开发人员。

1.3 术语

第三方机构：是提供闸机设备的供应商或开发商，负责向支队推送进场车辆数据，在本文中统称为第三方机构。

城市综合治理系统：是指负责接收第三方机构车辆数据的服务平台（以下简称为“我方”）。

2 接口概述

2.1 数据接入内容

进站原料运输车辆，通过闸机后，实时将车辆数据传输到支队，主要包括车牌号、车牌颜色、进站时间、进站车辆图片等。

2.2 数据传输方式

我方向第三方机构提供车辆数据接入服务接口，第三方机构定期将车辆数据主动推送到服务平台中。

2.3 数据推送流程

我方为每个第三方机构分配唯一的id编号(partner_id)和密钥(secret)，用于数据传输加密，防止被其他人员恶意使用和破坏，保证数据安全、可靠。流程如下图：

 

2.4 数据传输协议

接口协议基于标准HTTP协议，并且没有特殊的声明，请求均使用POST方式，请求头域(Header) Content-Type：application/form-data，请求体参数写入Body中。

2.5 数据加密规则

密钥(secret)是双方数据交互的基础，第三方机构必须严格保护本平台的合作密钥，不可泄漏，且严禁作为请求参数发送。若第三方机构相关开发人员变动，则应及时联系我司更换密钥。

加密算法采用AES对称加密机制保证数据传输安全。本文档每个接口都需要传partner_id 参数，用于辨别第三方身份。

（http://tool.chacuo.net/cryptaes   可用在线加密工具）

加/解密说明：

1．加/解密方式：AES-128-ECB；

2．填充方式：PKCS5Padding；

3. 请求参数/响应数据 data(json 字符串)作为待加/解密内容，合作密钥(secret)作为 AES 加/解密密钥，偏移量 iv 为空；

4. 采用 AES 加密方式传输时，请求/响应数据中诸如用户手机号、车牌号等隐私数

据不再需要单独处理。

2.6 数据交互规范 

Body请求数据字段说明：

KEY 字段	类型	必须字段	描述
partner_id	string	是	第三方id
data	string	是	参见具体接口参数(加密数据)

返回数据字段说明：

KEY 字段	类型	必须字段	描述
code	int	是	错误代码：1成功 非 1失败
msg	string	是	描述
data	json	是	返回数据

2.7 数据编码

请使用 utf-8 编码

2.8 接口服务地址

测试环境: https://IP:PORT/dev/第三方名称(联调前确定)/

正式环境: https://IP:PORT

2.9 Postman测试

data等参数要写在body中：

 

3 对外接口服务

3.1 实时推送入场记录

方法：/truck/push_entryRecord

描述：车辆驶入时，实时推送该入场记录

推送频率：实时

异常处置：推送消息不能丢失，推送不成功，继续推送，持续推送不成功，暂停5分钟，消息保留7日。

接口参数说明：

KEY字段	类型	必传参数	描述
record_id	string	是	进出站唯一id
companyid	string	是	所属企业ID
hphm	string	是	完整的车牌号
cpys	string	是	车牌颜色参见字典表：代码类别0728
colored	string	是	车辆颜色参见字典表：代码类别0730
entry_time	string	是	进站时间，秒级别格式为 yyyyMMddHHmmss，比如：20181227112153
entry_name	String	否	入口通道名称：如入场通道1
image_url	String	否	车辆入场图片云端可访问完整URL地址：

返回字段说明：

KEY字段	类型	必传参数	描述
code	int	是	错误代码：1成功 非 1失败
msg	string	是	描述

3.2 推送车辆入场图片

方法1：/truck/push_entryImg_url

描述：该功能接口用于车辆入站后单独采用URL全路径的方式推送车辆入场照片

推送频率：实时

异常处置：推送消息不能丢失，推送不成功，继续推送，持续推送不成功，暂停5分钟，消息保留7日。

接口参数说明：

KEY字段	类型	必须参数	描述
record_id	string	是	进出站唯一id
image_url	string	是	车辆入站图片云端可访问完整URL地址

方法2：/truck/push_entryImg_file

描述：该功能接口用于车辆入场后单独文件的方式（MultipartFile）推送车辆入场照片。

推送频率：实时

异常处置：推送消息不能丢失，推送不成功，继续推送，持续推送不成功，暂停5分钟，消息保留7日。

接口参数说明： 

KEY字段	类型	必须参数	描述
record_id	string	是	进出站唯一id
image_pic	string	是	File

返回字段说明：

KEY字段	类型	必传参数	描述
code	int	是	错误代码：1成功 非 1失败
msg	string	是	描述

4 附录

4.1 附录一、请求/响应加解密说明

加密类型	AES 对称加密
加密模式	ECB
偏移量	无
填充方式	PKCS5Padding
数据块长度	128
编码格式	UTF-8
输出编码	Base64
密钥	16 位随机字符串； 联调/上线前由我方提供

示例：

密钥：testparkservice

明文：test

密文：jolgIaHP+ML/8F2IfQB2nA==

4.2 附录二、请求示例说明

示例接口	信息同步
请求地址	/park/push_entryRecord
密钥	testparkservice
请求方式	POST
Content-Type	application/form-data
请求参数	partner_id	123456
	data（加密传输）	明文： {"park_id":"001","plate":"陕K629Z8","entry_time":1587744007} 密文： w6RffuW9RTAHLUUjbw2H2FRYKcf3QRwBDnHZ4Q4N1oZv45oDm1Zx3whXuwd5H6ESe7aqBQn1S2hGGId+lVoRDw==
响应结果	{ "code": 1, "msg": "success", }

注：

1. partner_id 联调/上线前由我方提供，用于标识第三方机构身份

4.3 附录三、字典表说明

代码类别	代码值	代码说明	代码类别说明
0728	0	蓝	车牌颜色
	1	黄
	2	黑
	3	白
0730	10	其他	车辆颜色
	11	黑色
	12	红色
	13	绿色
	14	黄色
	15	蓝色
	16	银色
	17	白色
	18	灰色
	10000	橙色

4.4 附录四、错误码说明

错误码	错误说明	备注
1	请求成功
0	请求失败	未知的错误
5003	无该第三方机构	无效的partner_id值
5004	签名校验/参数解密错误	参数 data 解密错误
5015	该第三方机构没有授权	第三方机构数据推送未打开推送数据权限或被关闭
200001	参数缺失	缺少必需的参数
200003	参数不在合理范围内	参数超过限制或类型错误
300002	企业companyid不存在