# 一、对接要求
1、设备使用4G物联网卡进行数据传输；
2、设备需支持在线/离线模式刷卡（或二维码扫码），支持黑白名单等功能；
3、设备需支持获取当前GPS经纬度、车速、车头朝向（角度）等信息，并间隔5s（可动态修改）上报一次；
4、设备需具备自己的后台/中间件，可对设备进行远程管理；
5、设备后台/中间件需对接嘟嘟接口，上传定位信息及刷卡信息、下载白名单信息等，具体请参考以下流程和文档。
# 二、对接流程
# 三、通用接口
# 流程说明
# 3.1 心跳包接口（上传定位、车速、验票模式等信息）
# 接口URL
- xxxx/location_report
# 请求方法
post
# 请求参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| device_id | string | 设备唯一id | Y |
| time | string | 设备当前时间 | Y |
| lng | string | 经度 | N |
| lat | string | 纬度 | N |
| course | string | 车辆当前行驶角度 | N |
| speed | string | 车辆当前行驶速度 | N |
| check_mode | int | 二维码验票模式(0在线验票，1离线验票) | Y |
| check_card_mode | int | 验卡模式(0在线验卡，1离线验卡) | Y |
| qrcode_mode | int | 二维码功能开关(0关闭，1开启) | Y |
| card_mode | int | IC卡功能开关(0关闭，1开启) | Y |
| white_mode | int | 白名单功能开关(0关闭，1开启) | Y |
| version_code_all | string | 刷卡验票白名单 全量版本号 | Y |
| version_code_add | string | 刷卡验票白名单 增量版本号 | Y |
| software_ver | int | 卡机固件版本 | Y |
| line_version_code_all | string | 线路白名单全量版本号 | Y |
| is_line_white | int | 是否限定线路白名单(0 否，1 是) | Y |
# 返回参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| enterprise_id | string | 所属企业ID | N |
| ret_code | int | 响应码(0表示成功，非0表示具体错误码) | Y |
| ret_msg | string | 错误信息 | Y |
| server_time | string | 服务器时间（格式年(18)月日时分秒） | Y |
| version_code | string | 密钥组版本号 | Y |
| check_mode | int | 验票模式(0在线验票，1离线验票) | Y |
| check_card_mode | int | 验卡模式(0在线验卡，1离线验卡) | Y |
| qrcode_mode | int | 二维码功能开关(0关闭，1开启) | Y |
| card_mode | int | IC卡功能开关(0关闭，1开启) | Y |
| white_mode | int | 白名单功能开关(0关闭，1开启) | Y |
| version_code_all | string | 刷卡验票白名单 全量版本号 | Y |
| version_code_add | string | 刷卡验票白名单 增量版本号 | Y |
| line_version_code_all | string | 线路白名单全量版本号 | Y |
| is_line_white | int | 是否限定线路白名单(0 否，1 是) | Y |
| check_start_time_format | string | 验票开始时间 | Y |
| check_end_time_format | string | 验票结束时间 | Y |
# 返回数据示例(json格式)
{
"req_id": "abcd",
"enterprise_id": "398",
"ret_code": 0,
"ret_msg": "成功",
"server_time": "190824162014",
"version_code": 1526005635,
"check_mode": "1",
"check_card_mode": "1",
"qrcode_mode": "1",
"card_mode": "1",
"white_mode": 1,
"version_code_all": "13604572",
"version_code_add": "53961084",
"line_version_code_all": "53961004",
"is_line_white": "1",
"check_start_time_format": "2023-08-03 07:45:00",
"check_end_time_format": "2023-08-03 09:45:00",
}
# 四、刷卡相关接口
# 流程说明
# 4.1刷卡验票白名单
# 接口URL
- xxxx/get_card_list
# 请求方法
post
# 请求参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| enterprise_id | string | 所属企业ID | N |
| token | string | 动态访问授权码 | Y |
| device_id | string | 设备唯一id | Y |
| type | int | 操作类型，1-全量，2-增量 | Y |
# 返回参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| enterprise_id | string | 所属企业ID | Y |
| time | int | 服务端处理耗时（单位：毫秒） | Y |
| ret_code | int | 响应码(0表示成功，非0表示具体错误码) | Y |
| ret_msg | string | 错误信息 | Y |
| version | string | 数据版本号 | Y |
| list | array | 卡号白名单列表 | Y |
| list - card_no | string | 卡号 | Y |
| list - flag | int | 用户状态（1:有效，0:无效） | Y |
# 返回数据示例(json格式)
{
"ret_code": 0,
"ret_msg": "成功",
"time": 600,
"req_id": "abcd",
"enterprise_id": '398',
"is_free": 1, // 【弃用】
"version": "52604317",
"list": [
{
"card_no": "",
"flag": "1",
"left_times": 1 // 【弃用】
},
{
"card_no": "00065537",
"flag": "1",
"left_times": 1
}
]
}
# 4.2刷卡验票接口（支持在线模式和离线模式）
###接口URL
- xxxx/card_check
# 请求方法
post
# 请求参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| check_mode | int | 校验模式，0在线验票，1离线验票（默认） | Y |
| device_id | string | 设备唯一id | Y |
| card_id | string | 物理卡id | Y |
| lng | string | 经度 | N |
| lat | string | 纬度 | N |
| time | string | 交易时间 | Y |
# 返回参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| ret_code | int | 响应码(0表示成功，非0表示具体错误码) | Y |
| sound_no | int | 语音序号(如果不为0 则用此语音序号对应的语音包播放) | Y |
| ret_msg | string | 错误信息 | Y |
# 返回数据示例(json格式)
{
"req_id": "abcd",
"ret_code":0,
"sound_no": 0,
"ret_msg":"成功"
}
# 4.3刷卡日志接口（用于离线模式，离线刷卡成功与否均要调用）
# 接口URL
- xxxx/card_check_log
# 请求方法
post
# 请求参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| device_id | string | 设备唯一id | Y |
| card_id | string | 物理卡id | Y |
| lng | string | 经度 | N |
| lat | string | 纬度 | N |
| time | string | 刷卡时间 | Y |
| status | string | 离线刷卡状态(0：正常，默认值；1：不在白名单内，2：在黑名单内) | N |
# 返回参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| ret_code | int | 响应码(0表示成功，非0表示具体错误码) | Y |
| ret_msg | string | 错误信息 | Y |
# 返回数据示例(json格式)
{
"req_id": "abcd",
"ret_code":0,
"ret_msg":"成功"
}
# 4.4 刷卡验票线路白名单
###接口URL
- xxxx/get_line_card_list
# 请求方法
post
# 请求参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| token | string | 动态访问授权码 | Y |
| device_id | string | 设备唯一id | Y |
| enterprise_id | string | 所属企业ID | N |
# 返回参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| enterprise_id | string | 所属企业ID | Y |
| time | int | 服务端处理耗时（单位：毫秒） | Y |
| ret_code | int | 响应码(0表示成功，非0表示具体错误码) | Y |
| ret_msg | string | 错误信息 | Y |
| version | string | 数据版本号 | Y |
| list | array | 卡号白名单列表 | Y |
# 返回数据示例(json格式)
{
"ret_code": 0,
"ret_msg": "成功",
"time": 600,
"req_id": "abcd",
"enterprise_id": '398',
"version": "52604317",
"list": [
{
"card_no": "",
"flag": "1",
"left_times": 1 // 【弃用】
},
{
"card_no": "00065537",
"flag": "1",
"left_times": 1
}
]
}
# 五、二维码相关接口
# 流程说明
# 5.2 获取二维码密钥组接口
# 接口URL
- xxxx/get_qrcode_keys
# 请求方法
post
# 请求参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| token | string | 动态访问授权码(通过获取token接口获取) | Y |
# 返回参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| ret_code | int | 响应码(0表示成功，非0表示具体错误码) | Y |
| ret_msg | string | 错误信息 | Y |
| version_code | string | 数据版本号 | Y |
| list | array | 密钥组 | Y |
| key_id | int | 密钥id | Y |
| key | string | 加密的密钥 |
# 返回数据示例(json格式)
{
"req_id":"abcd",
"ret_code": 0,
"ret_msg": "成功",
"version_code": 1526005635,
"list": [
{
"key_id": "1",
"key": "a84a6ce9"
},
{
"key_id": "2",
"key": "9c797cdb"
},
{
"key_id": "3",
"key": "c797cd9a"
},
{
"key_id": "4",
"key": "c7da847c"
}
]
}
# 5.3 二维码扫码验票接口（支持在线模式和离线模式）
###接口URL
- xxxx/ticket_check
# 请求方法
post
# 请求参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| check_mode | int | 校验模式，0在线验票，1离线验票 | Y |
| device_id | string | 设备唯一id | Y |
| qr_code | string | 扫码得到的加密字符串 | Y |
| lng | string | 经度 | N |
| lat | string | 纬度 | N |
| time | string | 验票时间 | Y |
# 返回参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| ret_code | int | 响应码(0表示成功，非0表示具体错误码) | Y |
| sound_no | int | 语音序号(如果不为0 则用此语音序号对应的语音包播放) | Y |
| ret_msg | string | 错误信息 | Y |
# 返回数据示例(json格式)
{
"req_id": "abcd",
"ret_code":0,
"sound_no": 0,
"ret_msg":"成功"
}
# 5.4 二维码扫码验票日志接口（用于离线模式，离线扫码成功与否均要调用）
###接口URL
- xxxx/offline_qrcode_log
# 请求方法
post
# 请求参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| device_id | string | 设备唯一id | Y |
| qr_code | string | 扫码得到的加密字符串 | Y |
| lng | string | 经度 | N |
| lat | string | 纬度 | N |
| time | string | 扫码时间 | Y |
| status | string | 离线扫码状态(0：正常，默认值；1：不在白名单内，2：在黑名单内) | N |
# 返回参数
| 名称 | 类型 | 说明 | 是否必须 |
|---|---|---|---|
| req_id | string | 请求ID | N |
| ret_code | int | 响应码(0表示成功，非0表示具体错误码) | Y |
| ret_msg | string | 错误信息 | Y |
# 返回数据示例(json格式)
{
"req_id":"abcd",
"ret_code":0,
"ret_msg":"成功"
}