常州智慧停车服务与管理信息系统接入规范.doc

1 18 常州智慧停车服务与管理信常州智慧停车服务与管理信 息系统接入规范息系统接入规范 拟拟 制制 人 人 审审 核核 人 人 批批 准准 人 人 I 18 文件变更记录文件变更记录 增加 修订 删除 版本号版本号日期日期变更类型变更类型修改人修改人摘摘 要要审核人审核人备注备注 城市代码改为必填 支付完成通知接口增加返回查价接口 得到的计费时间 收费记录上传接口显示上支付渠道字 段 由改为 心跳接口增加频率说明 增加和的说明 接口类型由调整为 调整为 增加字段类型 增加数据补传机制说明 I 18 目录目录 引言引言 编写目的 范围 术语定义 平台交互流程平台交互流程 移动支付临停费用交互流程 其它数据交互 停车场接入云平台流程停车场接入云平台流程 停车场申请接入信息 停车场厂商开发通信协议 停车场厂商接入测试服务器地址 停车场厂商接入正式服务器地址 接口调用规范接口调用规范 默认请求参数 接口约定 签名算法 例子 接口定义接口定义 接口总览 基础数据对接 车场信息同步 空车位数上传接口 通行数据对接 进出记录上传 II 18 收费记录上传 进出记录图片接口 临停收费对接 临停计费查询 临停支付完成通知 心跳接口 心跳接口 数据字典定义数据字典定义 车牌颜色 支付方式 车辆类型 收费方式 部分请求实例部分请求实例 1 18 1 引言引言 1 1 编写目的编写目的 主要描述了第三方停车场系统接入常州智慧停车服务与管理信息系统 以下简称 云平台 需要的接口和数据定义 为第三方停车场系统对接云平台提供接口依据 1 2 范围范围 本详细设计说明书的预期读者为 项目开发人员 项目测试人员 软件维护人员 1 3 术语定义术语定义 术语 缩略语术语 缩略语解解 释释 即 信息摘要算法 用于确保信息传输完整一致 是计算机广泛使 用的杂凑算法之一 又译摘要算法 哈希算法 上行下行 上行指停车场系统调用云平台接口 向云平台传输数据或者业务 下行指云平台调用停车场系统接口 向停车场系统传输数据或者业务 2 平台交互流程平台交互流程 2 1 移动支付临停费用交互流程移动支付临停费用交互流程 本交互流程描述的功能为 在常州智慧停车微信公众号或中 通过移动支付的方式 支付第三方 车场临停费用 具体流程说明如下 1 临停收费规则由第三方本地车场系统自行制定 云平台不进行干涉 2 使用现金支付时 本地车场系统直接调用本地车场服务端计算费用 完成支付后将账单明细同 步到云平台 3 线上支付停车费时 云平台需要向本地车场请求计费 由本地车场返回账单信息 4 线上支付完成后 通知本地车场 完成账单 并告知本地车场是否有优惠情况 5 本地车场完成账单后需要把账单明细同步到云平台 2 18 2 2 其它数据交互其它数据交互 3 停车场接入云平台流程停车场接入云平台流程 3 1 停车场申请接入信息停车场申请接入信息 停车场厂商向云平台申请接入 我方将提供以下数据 1 合作方应用标识 2 云平台版本信息 3 18 3 云平台验证加密密钥 4 测试服务器地址 待定 5 正式服务器地址 待定 3 2 停车场厂商开发通信协议停车场厂商开发通信协议 停车场调用云平台使用协议进行接口调用 具体规范参照 接口调用规范 3 3 停车场厂商接入测试服务器地址停车场厂商接入测试服务器地址 我方将提供测试服务器用以进行接入调试 接入服务器地址 待定 3 4 停车场厂商接入正式服务器地址停车场厂商接入正式服务器地址 接入服务器地址 待定 4 接口调用规范接口调用规范 4 1 默认请求参数默认请求参数 默认参数是指在所有请求中都必须携带的参数中 默认参数以方式传递 字段字段描述描述备注备注 停车场应用标识 由云平台统一分配 每个停车场分配唯一一个 时间戳 单位秒至今秒数 版本默认 密钥 由云平台统一分配不传递 只为 签名 作鉴权之用 详细生成方式见 4 2 接口约定接口约定 1 请求编码 中文需要编码 2 使用加密算法 4 3 签名算法签名算法 将所有业务参数组装为格式字符串 与 按字典序排序后拼接成字符串 然后该字符串进行加 密生成 4 18 注意 参数连接时需按参数名升序排序 输出结果为小写 拼接字符串时 参数要进行编码 4 4 例子例子 云平台获取的配置 固定参数 需要的数据 你好 的数据源 给进行排序 并对编码 结果 加密 结果 最终地址 5 18 云平台地址 的数据结果 5 接口定义接口定义 5 1 接口总览接口总览 实现内容实现内容模块模块功能点功能点接口接口 保证双方通讯心跳接口监测在线心跳接口 车场信息车场信息同步接口 基础数据 对接 空车位数上传空车位数上传接口 进出记录进出记录上传 收费记录收费记录上传 通行数据 对接 进出记录图片进出记录图片接口 临停计费查询 实现基本业务 数据交互 可 正常运行 临停收费 对接 临停计费 临停支付完成通知 5 2 数据补传机制 重要 数据补传机制 重要 当系统出现网络中断 接口故障或其他情况导致第三方停车场系统与云平台之前通讯出现异常 数据交互失败 第三方停车场系统需建立数据补传机制 通过上行心跳接口监测 监测频率分钟 当心跳接口不通时 中断数据上传 当心跳接口正常后 补传未上传数据和上传失败数据 直至全部 数据上传成功 5 3 心跳接口心跳接口 5 3 1 心跳接口心跳接口 接口类型 接口说明 车场和平台均需要此接口来相互检测是否在线 包含上行心跳接口和下行心跳接口 上行心跳接口频率为分钟 接口地址 上行服务地址 云平台地址 下行服务地址 厂商车场系统地址 参数类型 字符串 参数说明 6 18 属性属性名称名称类型类型说明说明 固定参数 标识字符串方式传递 版本号字符串方式传递 时间戳字符串方式传递 签名字符串方式传递 业务参数 返回结果 5 4 基础数据对接基础数据对接 车场需要将车场的基本信息同步给云平台 例如车场名 地址 收费标准 实时空余车位数等 5 4 1 车场信息同步车场信息同步 接口类型 接口说明 修改车场基本信息 如名称 地址 收费标准 接口地址 上行服务地址 云平台地址 参数类型 字符串 参数说明 属性属性名称名称类型类型说明说明 固定参数 标识字符串方式传递 版本号字符串方式传递 时间戳字符串方式传递 签名字符串方式传递 业务参数 车场名称字符串 必填 地址字符串 收费标准字符串 必填 城市代码字符串 必填 参照中华人民共和国国家统计局网 站发布的行政区划代码 7 18 经度浮点数 国测局 坐标 纬度浮点数 国测局 坐标 返回结果 5 4 2 空车位数上传接口空车位数上传接口 接口类型 接口说明 每隔秒 厂商主动上传一次最新的空车位数 接口地址 上行服务地址 云平台地址 参数类型 字符串 属性属性名称名称类型类型说明说明 固定参数 标识字符串方式传递 版本号字符串方式传递 时间戳字符串方式传递 签名字符串方式传递 业务参数 空车位数整型 必填 总车位数整型 必填 返回结果 5 5 通行数据对接通行数据对接 车场需要将车辆的进出记录 收费记录上传给云平台 8 18 5 5 1 进出记录上传进出记录上传 接口类型 接口说明 新增或更新进出记录 车场需要向平台实时上传车辆进出记录 接口地址 上行服务地址 云平台地址 参数类型 字符串 属性属性名称名称类型类型说明说明 固定参数 标识字符串方式传递 版本号字符串方式传递 时间戳字符串方式传递 签名字符串方式传递 业务参数 进出记录标识整型 必填 主键 入场和出场必须是不同的 通行时间日期时间必填 格式 车牌号字符串 必填 车牌颜色整型 必填 具体见说明 是否人工确认过 车牌 整型 否 是 对应收费记录标 识 整型 多次收费记录的 上传最后一次收 费记录的标识 记录类型整型 必填 入场 出场 返回结果 5 5 2 收费记录上传收费记录上传 接口类型 接口说明 新增或更新收费记录 车场需要向平台实时上传车辆收费记录 包含收费金额为的记 录 如月卡车等 接口地址 9 18 上行服务地址 云平台地址 参数类型 字符串 属性属性名称名称类型类型说明说明 固定参数 标识字符串方式传递 版本号字符串方式传递 时间戳字符串方式传递 签名字符串方式传递 业务参数 收费记录整型 必填 主键 一次停车分多次支付 每次支付的 不得重复 收费时间日期时间必填 格式 车牌号字符串 必填 车牌颜色整型 必填 具体见说明 开始时间日期时间必填 入场时间 格式 结束时间日期时间必填 添加账单时间 格式 收费方式整型 必填 具体见说明 支付方式整型 必填 具体见说明 线上支付渠道整形 必填 现金支付 第三方线上支付收费 即车场自 有渠道线上支付 常州智慧停车线上收费 即云平 台线上支付 应收浮点数 必填 单位 元 实收浮点数 必填 单位 元 车辆类型整型 具体见说明 优惠金额浮点数 单位 元 使用充值金额浮点数 单位 元 提前收费金额浮点数 单位 元 提前收费金额指出场前本次进出记 录已经收费的金额 会员卡优惠金额浮点数 单位 元 固定用户按临停 计算的优惠金额 浮点数 单位 元 如果按临停计费 账单的优惠金额 账单编号字符串 如果使用或者其他非现金支付方式 10 18 需要保留第三方支付账单编号 电子优惠券编号字符串 同时使用到多张电子优惠券时 将 编号以英文半角逗号形式连接 备注信息字符串 返回结果 5 5 3 进出记录图片接口进出记录图片接口 接口类型 接口说明 厂商主动上传每条停车记录的图片 注意此接口为请求 在固定参数中传递图片文件 流 接口地址 上行服务地址 云平台地址 参数类型 字符串 属性属性名称名称类型类型说明说明 固定参数 标识字符串方式传递 版本号字符串方式传递 时间戳字符串方式传递 签名字符串方式传递 图片文件流文件流方式传递 请求头为 业务参数 进出记录标识整型 必填 需要获取对应图片的进出记录的 记录图片的类型整型 必填 车牌小图 车身图 返回结果 11 18 5 6 临停收费对接临停收费对接 云平台与停车场系统进行临停收费相关功能的对接 5 6 1 临停计费查询临停计费查询 接口类型 接口说明 车场系统需要提供本地的临停计费接口 供平台进行调用 接口地址 下行服务地址 厂商车场系统地址 参数类型 字符串 参数说明 属性属性名称名称类型类型说明说明 固定参数 标识字符串方式传递 版本号字符串方式传递 时间戳字符串方式传递 签名字符串方式传递 业务参数 车牌号字符串 必填 计费时间日期时间必填 格式 返回结果 成功示例 是否成功 失败原因 京 车牌号 应收金额 扣除已收费 减免后的金额 减免金额 已收费金额 账单标识 若无则传 入场时间 计费时间 12 18 5 6 2 临停支付完成通知临停支付完成通知 接口类型 接口说明 通过平台接入的线上支付完成后通知车场系统完成缴费 接口地址 下行服务地址 厂商车场系统地址 参数类型 字符串 属性属性名称名称类型类型说明说明 固定参数 标识字符串方式传递 版本号字符串方式传递 时间戳字符串方式传递 签名字符串方式传递 业务参数 车牌号字符串 必填 账单标识整型 必填 计费接口返回的账单标识原样返回 计费时间日期时间必填 计费接口返回的计费时间原样返回 账单编号字符串 必填 平台支付账单编号 用于平台和本 地对账 支付金额浮点数 必填 实际支付金额 支付方式整型 必填 具体见说明 优惠金额浮点数 返回结果 13 18 6 数据字典定义数据字典定义 6 1 车牌颜色车牌颜色 标识标识内容内容 未知 蓝色 白色 黑色 黄色 绿色 6 2 支付方式支付方式 标识标识内容内容 现金支付 支付宝支付 微信支付 银联支付 6 3 车辆类型车辆类型 标识标识内容内容 小型车 中型车 大型车 军警车辆 6 4 收费方式收费方式 标识标识内容内容 出口收费 中央收