智管车开放接口(OAPI)调用文档

文档版本:v2.0
更新日期:2025-06-05
适用系统:智管车车辆管理平台
版权所有:贵州易迈思数据服务有限公司
DEMO示例:下载Java版


目录

  1. 概述
  2. 接口规范
  1. 接口数据类型(OapiIntfType)
  2. 操作类型(OapiOperType)
  3. 加密类型(OapiEncryptType)
  4. 接口详情
  1. 调用示例
  1. 返回码说明
  2. 常见问题

1. 概述

智管车开放接口(Open API,简称 OAPI)为第三方系统提供标准化的数据交换能力,支持对企业组织架构、车辆信息、司机信息、油卡信息、用车流程、费用记录和 GPS 位置等业务数据的查询、新增、修改、删除操作。


2. 接口规范

2.1 通讯方式

项目说明
协议HTTP
方法POST
编码UTF-8
Content-Typeapplication/json

2.2 请求地址

环境URL
生产环境https://zgc.zhiguanche.net/oapi

2.3 请求格式

统一使用 JSON 格式 POST 请求,请求体结构如下:

{
  "entCode": "1000130AF4",
  "intfType": "UseCarFlow",
  "operType": "QueryList",
  "enType": "None",
  "data": "{\"beginDate\":\"2025-01-01\",\"endDate\":\"2025-06-05\",\"dataStates\":\"0,10\",\"pageIndex\":1,\"pageSize\":10}"
}

请求字段说明:

字段类型必填说明
entCodeString单位编码(由智管车平台分配)
intfTypeOapiIntfType接口数据类型(枚举值或名称)
operTypeOapiOperType操作类型(枚举值或名称)
enTypeOapiEncryptType加密类型,默认为 None
dataString业务数据 JSON 字符串,如加密则为 Base64 MIME 字符串

2.4 响应格式

{
  "code": 0,
  "message": "成功",
  "data": "[{\"ent_code\":\"1000130AF4\",\"ent_name\":\"测试单位\"}]"
}

响应字段说明:

字段类型说明
codeint状态码:0-成功,1-失败
messageString提示消息(支持国际化)
dataString返回数据 JSON 字符串(查询列表时为 JSON 数组,分页查询时为包含 pageIndex/pageSize/totalCount/list 的 JSON 对象;如加密则为 Base64 MIME 字符串)

2.5 加密方式

支持三种加密方式,由 enType 字段控制:

enType说明密钥
None (0)不加密无需密钥
Rsa (1)RSA 非对称加密由智管车平台生成 RSA 密钥对,私钥保留在平台,公钥提供给调用方
Aes (2)AES 对称加密由智管车平台生成 AES 密钥(Base64 编码),提供给调用方

加密流程(以 AES 为例):

请求加密:

  1. 构造业务 data JSON 字符串
  2. 将 data 按 UTF-8 转为 byte[]
  3. 使用 AES/ECB/PKCS5Padding 算法加密 byte[]
  4. 将加密结果编码为 Base64 MIME 字符串,写回 data 字段
  5. 整体 RequestInfo 序列化为 JSON 发送

响应解密(反向流程):

  1. 取出 ReturnInfo.data 的 Base64 MIME 字符串
  2. 解码为 byte[]
  3. 使用相同的 AES 密钥解密 byte[]
  4. 将解密结果按 UTF-8 转为 JSON 字符串

算法参数:

算法详细参数
AESAES/ECB/PKCS5Padding,密钥长度 128 位
RSARSA/ECB/PKCS1Padding,密钥长度 1024 位,支持分段加解密(最大加密 117 字节/最大解密 128 字节)

2.6 调用频率限制


3. 接口数据类型(OapiIntfType)

枚举值编号中文说明所属模块
Enterprise1000单位信息企业组织
Branch1001部门信息企业组织
Role1002角色信息企业组织
User1003用户信息企业组织
CarGroup2000车辆分组车辆/司机/油卡
CarInfo2001车辆信息车辆/司机/油卡
DriverGroup2010司机分组车辆/司机/油卡
DriverInfo2011司机信息车辆/司机/油卡
OilCardGroup2020油卡分组车辆/司机/油卡
OilCardInfo2021油卡信息车辆/司机/油卡
EtcCardGroup2022ETC卡分组车辆/司机/油卡
EtcCardInfo2023ETC卡信息车辆/司机/油卡
UseCarFlow3000用车申请流程流程相关
Charge4000费用信息费用
UseCarRecord5000用车登记用车
GpsRealInfo6000车辆实时位置信息GPS
GpsRoute6001车辆行驶轨迹数据GPS
GpsStay6002车辆停留信息GPS

4. 操作类型(OapiOperType)

枚举值编号中文说明
QueryList1000查询列表
QueryDetail1001查询明细(仅用车流程可用)
Add2000增加
Update3000更新
UseCarFlowCancel3001用车流程作废
Delete4000删除

5. 加密类型(OapiEncryptType)

枚举值编号中文说明
None0不加密
Rsa1RSA 非对称加密
Aes2AES 对称加密

6. 接口详情

6.1 单位信息 - Enterprise (1000)

支持的操作矩阵

操作支持说明
QueryList查询本单位信息(始终只有一条记录)
QueryDetail同 QueryList
Update更新本单位信息
Add接口不支持增加单位信息
Delete接口不支持删除单位信息

QueryList 请求参数

{}

无需传入参数,data 字段可传空字符串。

QueryList 响应示例

[{
  "ent_code": "1000130AF4",
  "createtime": "2024-01-01 00:00:00",
  "ent_name": "测试单位",
  "organization_code": "ORG001",
  "address": "贵阳市观山湖区",
  "linkman": "张三",
  "linkphone": "13800138000",
  "principal": "李四",
  "principal_phone": "13900139000",
  "email": "test@example.com",
  "web_address": "www.example.com",
  "intro": "单位简介",
  "ent_user_id": "admin"
}]

返回字段说明:

字段类型说明
ent_codeString单位编码
createtimeString创建时间
ent_nameString单位名称
organization_codeString组织机构代码
addressString地址
linkmanString联系人
linkphoneString联系电话
principalString负责人
principal_phoneString负责人电话
emailString邮箱
web_addressString网址
introString简介
ent_user_idString单位管理员用户 ID

Update 请求参数

{
  "ent_name": "新单位名称",
  "organization_code": "NEWORG001",
  "address": "新地址",
  "linkman": "新联系人",
  "linkphone": "13700137000",
  "principal": "新负责人",
  "principal_phone": "13600136000",
  "email": "new@example.com",
  "web_address": "new.example.com",
  "intro": "新简介"
}

建议先调用 QueryList 获取当前数据,再修改需要更新的字段后传回。


6.2 部门信息 - Branch (1001)

支持的操作矩阵

操作支持说明
QueryList查询本单位的部门列表
Add新增部门
Update修改部门信息
Delete接口不支持删除部门信息

QueryList 请求参数

{}

QueryList 响应示例

[{
  "organ_id": 10001,
  "organ_code": "DEPT001",
  "organ_name": "技术部",
  "organ_phone": "0851-1234567",
  "organ_man": "王经理"
}]

返回字段说明:

字段类型说明
organ_idLong部门 ID
organ_codeString部门编码
organ_nameString部门名称
organ_phoneString部门电话
organ_manString部门负责人

Add 请求参数

{
  "organ_code": "DEPT002",
  "organ_name": "财务部",
  "organ_phone": "0851-7654321",
  "organ_man": "赵总监"
}

organ_id 由系统自动通过存储过程 sp_sys_getseqmaxid 生成,无需传入。

Add 响应示例

[{
  "organ_id": 10002,
  "organ_code": "DEPT002",
  "organ_name": "财务部",
  "organ_phone": "0851-7654321",
  "organ_man": "赵总监"
}]

Update 请求参数

{
  "organ_id": 10001,
  "organ_code": "DEPT001-NEW",
  "organ_name": "新技术部",
  "organ_phone": "0851-1111111",
  "organ_man": "钱经理"
}

6.3 角色信息 - Role (1002)

支持的操作矩阵

操作支持说明
QueryList查询本单位的角色列表
Add接口不支持增加角色信息
Update接口不支持修改角色信息
Delete接口不支持删除角色信息

QueryList 请求参数

{}

QueryList 响应示例

[{
  "role_id": 20001,
  "role_code": "ADMIN",
  "role_name": "管理员"
}]

返回字段说明:

字段类型说明
role_idLong角色 ID
role_codeString角色编码
role_nameString角色名称

6.4 用户信息 - User (1003)

支持的操作矩阵

操作支持说明
QueryList查询本单位的用户列表
Add新增用户
Update修改用户信息
Delete接口不支持删除用户信息

QueryList 请求参数

{}

QueryList 响应示例

[{
  "user_id": "U001",
  "user_name": "张三",
  "organ_id": 10001,
  "role_id": 20001,
  "headship": 1,
  "create_time": "2024-01-01T10:00:00",
  "state": 1,
  "mobilephone": "13800138000",
  "email": "zhangsan@example.com",
  "sex": 1,
  "authorize_handon": true,
  "is_organ_leader": false
}]

返回字段说明:

字段类型说明
user_idString用户 ID
user_nameString用户名
organ_idLong所属部门 ID
role_idLong角色 ID
headshipInteger职务
create_timeString创建时间
stateInteger状态
mobilephoneString手机号
emailString邮箱
sexInteger性别
authorize_handonBoolean是否授权
is_organ_leaderBoolean是否为部门负责人

Add 请求参数

{
  "user_name": "新用户",
  "organ_id": 10001,
  "role_id": 20001,
  "headship": 1,
  "state": 1,
  "mobilephone": "13900139000",
  "email": "new@example.com",
  "sex": 1,
  "authorize_handon": false,
  "is_organ_leader": false
}

user_id 由系统通过 IUserService.GetNewUserId() 自动生成,无需传入。

Add 响应示例

[{
  "user_id": "U002",
  "user_name": "新用户",
  "organ_id": 10001,
  "role_id": 20001,
  "headship": 1,
  "create_time": "2025-06-05T10:00:00",
  "state": 1,
  "mobilephone": "13900139000",
  "email": "new@example.com",
  "sex": 1,
  "authorize_handon": false,
  "is_organ_leader": false
}]

Update 请求参数

{
  "user_id": "U001",
  "user_name": "张三(已修改)",
  "organ_id": 10002,
  "role_id": 20002,
  "headship": 2,
  "state": 0,
  "mobilephone": "13700137000",
  "email": "modified@example.com",
  "sex": 1,
  "authorize_handon": true,
  "is_organ_leader": true
}

6.5 车辆分组 - CarGroup (2000)

支持的操作矩阵

操作支持说明
QueryList查询车辆分组列表
Add新增车辆分组
Update修改车辆分组
Delete删除车辆分组(级联将车辆的分组 ID 置 0)

QueryList 请求参数

{}

QueryList 响应示例

[{
  "group_id": 30001,
  "group_order": 1,
  "group_name": "公务用车"
}]

返回字段说明:

字段类型说明
group_idLong分组 ID
group_orderInteger排序号
group_nameString分组名称

Add 请求参数

{
  "group_order": 100,
  "group_name": "新分组"
}

注:group_id 字段在实现中以 group_order 的值作为 ID 传入,建议 group_order 使用唯一值。

Add 响应示例

[{
  "ent_code": "1000130AF4",
  "group_id": 100,
  "group_order": 100,
  "group_name": "新分组"
}]

Update 请求参数

{
  "group_id": 30001,
  "group_order": 2,
  "group_name": "公务用车(已修改)"
}

Delete 请求参数

{
  "group_id": 30001
}

删除操作在事务中执行:先删除 zgc_car_group 记录,再将 zgc_car_info 中该分组的关联置为 0。


6.6 车辆信息 - CarInfo (2001)

支持的操作矩阵

操作支持说明
QueryList查询车辆列表
Update仅支持变更所属分组(group_id)
Add接口不支持增加车辆
Delete接口不支持删除车辆

QueryList 请求参数

{}

QueryList 响应示例

[{
  "car_id": 40001,
  "create_time": "2024-01-01T10:00:00",
  "group_id": 30001,
  "plate_number": "贵A66666",
  "plate_color": 1,
  "car_model": "大众帕萨特",
  "car_level": 1,
  "buy_date": "2023-06-01",
  "seat_count": 5,
  "car_state": 1,
  "vin_no": "LSVXXXXX123456789",
  "engine_no": "ENG123456",
  "mileage": 50000.00,
  "insurance_cycle": 365,
  "audit_cycle": 365,
  "repair_distance_cycle": 10000,
  "repair_month_cycle": 6,
  "repair_last_time": "2024-12-01",
  "insurance_last_time": "2025-01-01",
  "audit_last_time": "2025-03-01",
  "insurance_busi_time": "2025-01-01",
  "insurance_goods_time": "2025-01-01",
  "insurance_driver_time": "2025-01-01",
  "repair_last_mileage": 45000.00,
  "device_num": "GPS001"
}]

返回字段说明:

字段类型说明
car_idLong车辆 ID
create_timeString创建时间
group_idLong分组 ID
plate_numberString车牌号
plate_colorInteger车牌颜色
car_modelString车辆型号
car_levelInteger车辆等级
buy_dateString购买日期
seat_countInteger座位数
car_stateInteger车辆状态
vin_noString车架号
engine_noString发动机号
mileageDouble里程
insurance_cycleInteger保险周期(天)
audit_cycleInteger年审周期(天)
repair_distance_cycleInteger保养里程周期
repair_month_cycleInteger保养月份周期
repair_last_timeString上次保养时间
insurance_last_timeString上次保险时间
audit_last_timeString上次年审时间
insurance_busi_timeString商业险到期时间
insurance_goods_timeString货物险到期时间
insurance_driver_timeString驾驶员险到期时间
repair_last_mileageDouble上次保养里程
device_numStringGPS 设备号

Update 请求参数

{
  "car_id": 40001,
  "group_id": 30002
}

仅支持变更车辆所属分组(group_id)。


6.7 司机分组 - DriverGroup (2010)

支持的操作矩阵

操作支持说明
QueryList查询司机分组列表
Add新增司机分组
Update修改司机分组
Delete删除司机分组(级联将司机的分组 ID 置 0)

接口字段和模式与「车辆分组 - CarGroup (2000)」完全一致,详见 6.5 节。


6.8 司机信息 - DriverInfo (2011)

支持的操作矩阵

操作支持说明
QueryList查询司机列表
Update仅支持变更所属分组(group_id)
Add接口不支持增加司机
Delete接口不支持删除司机

QueryList 请求参数

{}

QueryList 响应示例

[{
  "driver_id": 50001,
  "group_id": 35001,
  "user_id": "U001",
  "create_time": "2024-01-01T10:00:00",
  "driver_name": "张三",
  "driver_phone": "13800138000",
  "short_phone": "6666",
  "driver_sex": 1,
  "driver_birthday": "1990-01-01",
  "lic_type": "C1",
  "lic_time": "2010-06-01",
  "driver_state": 1,
  "memo": ""
}]

返回字段说明:

字段类型说明
driver_idLong司机 ID
group_idLong分组 ID
user_idString关联用户 ID
create_timeString创建时间
driver_nameString司机姓名
driver_phoneString司机电话
short_phoneString短号
driver_sexInteger性别
driver_birthdayString出生日期
lic_typeString驾驶证类型
lic_timeString领证时间
driver_stateInteger司机状态
memoString备注

Update 请求参数

{
  "driver_id": 50001,
  "group_id": 35002
}

仅支持变更司机所属分组(group_id)。


6.9 油卡分组 - OilCardGroup (2020)

支持的操作矩阵

操作支持说明
QueryList查询油卡分组列表
Add新增油卡分组
Update修改油卡分组
Delete删除油卡分组(级联将油卡的分组 ID 置 0)

接口字段和模式与「车辆分组 - CarGroup (2000)」完全一致,详见 6.5 节。


6.10 油卡信息 - OilCardInfo (2021)

支持的操作矩阵

操作支持说明
QueryList查询油卡列表
Update仅支持变更所属分组(group_id)
Add接口不支持增加油卡
Delete接口不支持删除油卡

QueryList 请求参数

{}

QueryList 响应示例

[{
  "card_id": 60001,
  "group_id": 40001,
  "card_type": 1,
  "card_num": "CARD001",
  "current_amount": 5000.00,
  "card_state": 1,
  "bind_type": 1,
  "bind_id": 40001,
  "bind_name": "贵A66666",
  "owner_name": "张三",
  "owner_phone": "13800138000",
  "memo": ""
}]

返回字段说明:

字段类型说明
card_idLong油卡 ID
group_idLong分组 ID
card_typeInteger卡类型
card_numString卡号
current_amountDouble当前余额
card_stateInteger卡状态
bind_typeInteger绑定类型
bind_idLong绑定对象 ID
bind_nameString绑定对象名称
owner_nameString持卡人姓名
owner_phoneString持卡人电话
memoString备注

Update 请求参数

{
  "card_id": 60001,
  "group_id": 40002
}

仅支持变更油卡所属分组(group_id)。


6.11 ETC卡分组 - EtcCardGroup (2022)

支持的操作矩阵

操作支持说明
QueryList查询ETC卡分组列表
Add新增ETC卡分组
Update修改ETC卡分组
Delete删除ETC卡分组(级联将ETC卡的分组 ID 置 0)

接口字段和模式与「车辆分组 - CarGroup (2000)」完全一致,详见 6.5 节。


6.12 ETC卡信息 - EtcCardInfo (2023)

支持的操作矩阵

操作支持说明
QueryList查询ETC卡列表
Update仅支持变更所属分组(group_id)
Add接口不支持增加ETC卡
Delete接口不支持删除ETC卡

QueryList 请求参数

{}

QueryList 响应示例

[{
  "card_id": 70001,
  "group_id": 50001,
  "card_type": 0,
  "card_num": "ETC001",
  "current_amount": 2000.00,
  "card_state": 1,
  "bind_type": 1,
  "bind_id": 40001,
  "bind_name": "贵A66666",
  "owner_name": "张三",
  "owner_phone": "13800138000",
  "memo": ""
}]

返回字段说明:

字段类型说明
card_idLongETC卡 ID
group_idLong分组 ID
card_typeInteger卡类型(0=ETC卡)
card_numStringETC卡号
current_amountDouble当前余额
card_stateInteger卡状态
bind_typeInteger绑定类型
bind_idLong绑定对象 ID
bind_nameString绑定对象名称
owner_nameString持卡人姓名
owner_phoneString持卡人电话
memoString备注

Update 请求参数

{
  "card_id": 70001,
  "group_id": 50002
}

仅支持变更ETC卡所属分组(group_id)。


6.13 用车申请流程 - UseCarFlow (3000)

支持的操作矩阵

操作支持说明
QueryList分页查询用车流程列表
QueryDetail查询用车流程明细(含审批记录和行车记录)
Add接口暂不支持申请
Update接口暂不支持修改
UseCarFlowCancel接口暂不支持作废
Delete接口暂不支持删除

QueryList 请求参数

{
  "beginDate": "2025-01-01",
  "endDate": "2025-06-05",
  "dataStates": "0,10",
  "pageIndex": 1,
  "pageSize": 10
}

请求参数说明:

字段类型必填说明
beginDateString查询起始日期,格式 yyyy-MM-dd
endDateString查询结束日期,格式 yyyy-MM-dd
dataStatesString数据状态,空为全部,逗号分隔多个状态:0-待提交;1-被打回;10-流程中;20-已完成;30-已作废
pageIndexInteger页码,从 1 开始,默认 1
pageSizeInteger每页行数,默认 10

QueryList 响应示例

{
  "pageIndex": 1,
  "pageSize": 10,
  "totalCount": 50,
  "list": [
    {
      "useNum": "YC20250605001",
      "entCode": "1000130AF4",
      "flowId": 10001,
      "nodeId": 20001,
      "dataState": 10,
      "createTime": "2025-06-05T09:00:00",
      "applyUserid": "U001",
      "applyUsername": "张三",
      "applyOrganid": 10001,
      "applyOrganname": "技术部",
      "applyType": 1,
      "useUserid": "U001",
      "useUsername": "张三",
      "applyBeginTime": "2025-06-05T14:00:00",
      "applyEndTime": "2025-06-05T18:00:00",
      "startPlace": "公司",
      "passPlaceInfo": "",
      "targetPlace": "客户现场",
      "placeLonLat": "",
      "needDriver": false,
      "peopleNumber": 3,
      "carLevel": 1,
      "useType": 1,
      "useReason": "拜访客户",
      "customFields": "",
      "carId": 40001,
      "carInfo": "贵A66666",
      "driverId": 50001,
      "driverInfo": "张三",
      "realBeginTime": "2025-06-05T14:10:00",
      "realEndTime": null,
      "useRecordid": null,
      "beginMileage": 50000.0,
      "endMileage": null,
      "beginMileageImage": "",
      "endMileageImage": "",
      "sbRecordId": null,
      "nodeName": "部门经理审批",
      "carImage": "",
      "nodeType": 1,
      "nodeOrder": 1,
      "sameOrgAudit": false,
      "pickUser": 0,
      "returnUser": 0,
      "driverUserId": "U001",
      "deviceNum": "GPS001",
      "lastRemark": ""
    }
  ]
}

FlowUseRecord 字段说明:

字段类型说明
useNumString申请单号
entCodeString单位编码
flowIdLong流程 ID
nodeIdLong节点 ID
dataStateInteger数据状态:0-待提交, 1-被打回, 10-流程中, 20-已完成, 30-已作废
createTimeString申请时间
applyUseridString申请人 ID
applyUsernameString申请人
applyOrganidLong所属部门 ID
applyOrgannameString所属部门
applyTypeInteger申请类型
useUseridString用车人 ID
useUsernameString用车人
applyBeginTimeString申请出车时间
applyEndTimeString申请返车时间
startPlaceString起始地
passPlaceInfoString途经点
targetPlaceString目的地
placeLonLatString地点经纬度
needDriverBoolean是否需要司机
peopleNumberInteger随车人数
carLevelInteger车辆类型
useTypeInteger用车属性
useReasonString用车事由
customFieldsString自定义字段
carIdLong车辆 ID
carInfoString车辆信息
driverIdLong司机 ID
driverInfoString司机信息
realBeginTimeString实际出车时间
realEndTimeString实际返车时间
useRecordidLong用车记录 ID
beginMileageDouble提车时里程
endMileageDouble还车时里程
beginMileageImageString提车里程照片
endMileageImageString还车里程照片
sbRecordIdLong记录 ID
nodeNameString当前节点名称
carImageString车辆图片
nodeTypeInteger节点类型
nodeOrderInteger节点顺序
sameOrgAuditBoolean是否同部门审批
pickUserInteger取车人
returnUserInteger还车人
driverUserIdString司机用户 ID
deviceNumStringGPS 设备号
lastRemarkString最近备注

QueryDetail 请求参数

{
  "use_num": "YC20250605001"
}

QueryDetail 响应示例

{
  "data": {
    "use_num": "YC20250605001",
    "data_state": 10,
    "create_time": "2025-06-05T09:00:00",
    "apply_username": "张三",
    "apply_organname": "技术部",
    "use_username": "张三",
    "apply_begin_time": "2025-06-05T14:00:00",
    "apply_end_time": "2025-06-05T18:00:00",
    "start_place": "公司",
    "target_place": "客户现场",
    "people_number": 3,
    "need_driver": false,
    "car_level": 1,
    "use_reason": "拜访客户",
    "car_info": "贵A66666",
    "driver_info": "张三",
    "real_begin_time": "2025-06-05T14:10:00",
    "real_end_time": null,
    "begin_mileage": 50000.0,
    "end_mileage": null
  },
  "auditList": [
    {
      "record_id": 1,
      "use_num": "YC20250605001",
      "record_time": "2025-06-05T09:30:00",
      "record_type": 1,
      "oper_username": "李四",
      "remark": "同意",
      "pre_node_name": "提交申请",
      "post_node_name": "部门经理审批"
    }
  ],
  "routeList": [
    {
      "record_id": 1,
      "use_num": "YC20250605001",
      "begin_time": "2025-06-05T14:10:00",
      "begin_mileage": 50000.0,
      "begin_addr": "公司",
      "end_time": null,
      "end_mileage": null,
      "end_addr": null,
      "memo": ""
    }
  ]
}

auditList(审批记录)字段说明:

字段类型说明
record_idLong记录 ID
use_numString申请单号
record_timeString审批时间
record_typeInteger审批类型
oper_usernameString操作人
remarkString审批意见
pre_node_nameString前节点名称
post_node_nameString后节点名称

routeList(行车记录)字段说明:

字段类型说明
record_idLong记录 ID
use_numString申请单号
begin_timeString出车时间
begin_mileageDouble出车里程
begin_addrString出车地址
end_timeString还车时间
end_mileageDouble还车里程
end_addrString还车地址
memoString备注

6.14 费用信息 - Charge (4000)

支持的操作矩阵

操作支持说明
QueryList分页查询费用列表(dataState=-3 时同时返回加油打回记录)
Add接口不支持增加
Update接口不支持修改
Delete接口不支持删除

QueryList 请求参数

{
  "beginDate": "2025-01-01",
  "endDate": "2025-06-05",
  "dataState": -1,
  "pageIndex": 1,
  "pageSize": 10
}

请求参数说明:

字段类型必填说明
beginDateString查询起始日期,格式 yyyy-MM-dd
endDateString查询结束日期,格式 yyyy-MM-dd
dataStateInteger数据状态:-1-全部;-2-已提交和存档的;-3-草稿和打回的(含加油打回);0-草稿;1-已提交;10-已存档;20-打回的
pageIndexInteger页码,从 1 开始,默认 1
pageSizeInteger每页行数,默认 10

QueryList 响应示例

{
  "pageIndex": 1,
  "pageSize": 10,
  "totalCount": 50,
  "list": [
    {
      "entCode": "1000130AF4",
      "recordId": 70001,
      "plateNumber": "贵A66666",
      "state": 1,
      "createTime": "2025-06-05T10:00:00",
      "operUserId": "U001",
      "operUserName": "张三",
      "carId": 40001,
      "reviewTime": null,
      "auditUserName": "",
      "auditReason": "",
      "driverId": 50001,
      "useRecordId": 80001,
      "amount": 300.00,
      "beginDate": "2025-06-05T10:30:00",
      "chargeLink": false,
      "linkRecordType": 0,
      "driverInfo": "张三",
      "userId": "U001",
      "chargeType": 1,
      "oilCardId": null,
      "userName": "张三",
      "memo": "加油费",
      "linkRecordId": ""
    }
  ]
}

BookChargeRecord 字段说明:

字段类型说明
entCodeString单位编码
recordIdLong记录 ID
plateNumberString车牌号
stateInteger状态
createTimeString录入时间
operUserIdString录入人 ID
operUserNameString录入人
carIdLong车辆 ID
reviewTimeString审核时间
auditUserNameString审核人
auditReasonString审核意见
driverIdLong司机 ID
useRecordIdLong用车记录 ID
amountDouble金额
beginDateString费用发生时间
chargeLinkBoolean是否关联费用
linkRecordTypeInteger关联类型
driverInfoString司机信息
userIdString用户 ID
chargeTypeInteger费用类别(见下方说明)
oilCardIdLong油卡 ID
userNameString用车人
memoString备注
linkRecordIdString关联 ID

chargeType 费用类别对照:

说明说明
1加油费2充电费
3停车费4通行费
5洗车费6罚单费
7油电卡充值费8汽车用品费
9货运费10租车费
11尿素费12信息费
13司机工资14餐饮费
15住宿费16加班费
30保养费31年审费
32保险费33故障维修费
34事故维修费90购车费
91购置税100其他费用

dataState=-3 时的补充加油打回记录(BookOilRecord 字段说明):

字段类型说明
entCodeString单位编码
recordIdLong记录 ID
plateNumberString车牌号
stateInteger状态
createTimeString录入时间
operUserIdString录入人 ID
operUserNameString录入人
carIdLong车辆 ID
useRecordIdLong用车记录 ID
driverIdLong司机 ID
beginDateString加油/电时间
oilTypeString加油/电型号
oilEntString加油电站
oilAmountDouble金额
unitPriceDouble单价
odographCountDouble加油电时公里数
driverInfoString司机
oilCardIdLong油卡 ID
oilCardNumString油卡卡号
userNameString用车人
memoString备注
userIdString用车人 ID

6.15 用车登记 - UseCarRecord (5000)

支持的操作矩阵

操作支持说明
QueryList分页查询用车登记列表
Add接口暂不支持申请
Update接口暂不支持修改
Delete接口暂不支持删除

QueryList 请求参数

{
  "beginDate": "2025-01-01",
  "endDate": "2025-06-05",
  "dataState": -1,
  "pageIndex": 1,
  "pageSize": 10
}

请求参数说明:

字段类型必填说明
beginDateString查询起始日期,格式 yyyy-MM-dd
endDateString查询结束日期,格式 yyyy-MM-dd
dataStateInteger数据状态:-1-全部;-2-已收车和存档的;-3-出车中和打回的;0-出车中;1-已收车;10-已存档;20-打回
pageIndexInteger页码,从 1 开始,默认 1
pageSizeInteger每页行数,默认 10

QueryList 响应示例

{
  "pageIndex": 1,
  "pageSize": 10,
  "totalCount": 50,
  "list": [
    {
      "beginDate": "2025-06-05T14:00:00",
      "beginMileage": 50000.0,
      "useReason": "拜访客户",
      "useName": "张三",
      "usePhone": "13800138000",
      "useUserId": "U001",
      "startPlace": "公司",
      "targetPlace": "客户现场",
      "driverInfo": "张三",
      "driverPhone": "13800138000",
      "driverId": 50001,
      "followMan": "",
      "followPhone": "",
      "followId": null,
      "followIsDriver": false,
      "useOrganName": "技术部",
      "useOrganId": 10001,
      "beginCustomFields": "",
      "endDate": null,
      "endMileage": null,
      "memo": "",
      "endCustomFields": ""
    }
  ]
}

BookUseRecord 字段说明:

字段类型说明
beginDateString用车时间
beginMileageDouble出车里程
useReasonString用车事由
useNameString用车人/单位
usePhoneString用车人电话
useUserIdString用车人用户 ID
startPlaceString出发地
targetPlaceString目的地
driverInfoString驾驶员
driverPhoneString驾驶员电话
driverIdLong驾驶员 ID
followManString跟车员
followPhoneString跟车员电话
followIdLong跟车员 ID
followIsDriverBoolean跟车员是司机
useOrganNameString用车部门
useOrganIdLong用车部门 ID
beginCustomFieldsString出车自定义字段
endDateString收车时间
endMileageDouble收车里程
memoString备注
endCustomFieldsString收车自定义字段

6.16 车辆实时位置 - GpsRealInfo (6000)

支持的操作矩阵

操作支持说明
QueryList查询车辆实时位置列表
QueryDetail同 QueryList
其他不支持其他操作

QueryList 请求参数

{
  "groupId": 0,
  "plateNumber": "",
  "state": 0
}

请求参数说明:

字段类型必填说明
groupIdLong车辆分组 ID,传 0 则忽略条件
plateNumberString车牌号,传空则查单位全部车辆
stateInteger行驶状态:0-离线;1-行驶;2-停留

QueryList 响应示例

[{
  "deviceNum": "GPS001",
  "carId": 40001,
  "lastState": 1,
  "lastTime": "2025-06-05T14:30:00",
  "validTime": "2025-06-05T14:30:00",
  "posLatitude": 26.647,
  "posLongitude": 106.63,
  "mileage": 50000.0,
  "fuelConsumption": 8.5,
  "speed": 60.0,
  "altitude": 1200,
  "isAcc": true,
  "isLocationing": true,
  "isSupply": false,
  "direction": 90,
  "isPoweroff": false,
  "lastPosId": 100001,
  "lastAccId": 100002,
  "plateNumber": "贵A66666",
  "groupId": 30001,
  "useNum": "YC20250605001",
  "posAddr": "贵阳市观山湖区"
}]

GnssLastpos 字段说明:

字段类型说明
deviceNumString设备号
carIdLong车辆 ID
lastStateInteger行驶状态:0-离线;1-行驶;2-停留
lastTimeString最后定位时间
validTimeString有效时间
posLatitudeDouble纬度
posLongitudeDouble经度
mileageDouble里程(km)
fuelConsumptionDouble油耗
speedDouble速度(km/h)
altitudeInteger海拔(米)
isAccBooleanACC 状态
isLocationingBoolean是否卫星定位
isSupplyBoolean是否补传
directionInteger方向(0-360度)
isPoweroffBoolean主电源是否掉电
lastPosIdLong最后位置 ID
lastAccIdLong最后 ACC ID
plateNumberString车牌号
groupIdLong分组 ID
useNumString用车申请编号
posAddrString位置地址描述

6.17 车辆行驶轨迹 - GpsRoute (6001)

支持的操作矩阵

操作支持说明
QueryList查询车辆行驶轨迹
QueryDetail同 QueryList
其他不支持其他操作

QueryList 请求参数

{
  "plateNumber": "贵A66666",
  "useNum": "",
  "startTime": "2025-06-05 08:00:00",
  "endTime": "2025-06-05 18:00:00"
}

请求参数说明:

字段类型必填说明
plateNumberString车牌号(必需传入)
useNumString用车申请编号
startTimeString查询范围开始时间,格式 yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss
endTimeString查询范围结束时间

注意:一次查询最多返回 5000 条轨迹点。如果查询结果超过 5000 条,请缩小查询时间范围。

QueryList 响应示例

[{
  "posId": 200001,
  "deviceNum": "GPS001",
  "carId": 40001,
  "useNum": "YC20250605001",
  "createTime": "2025-06-05T14:30:00",
  "posLatitude": 26.647,
  "posLongitude": 106.63,
  "mileage": 50000.0,
  "fuelConsumption": 8.5,
  "speed": 60.0,
  "altitude": 1200,
  "isPoweroff": false,
  "isAcc": true,
  "isLocationing": true,
  "isSupply": false,
  "direction": 90,
  "plateNumber": "贵A66666"
}]

GnssPosition 字段说明:

字段类型说明
posIdLong位置 ID
deviceNumString设备号
carIdLong车辆 ID
useNumString用车申请编号
createTimeString定位时间
posLatitudeDouble纬度
posLongitudeDouble经度
mileageDouble里程(km)
fuelConsumptionDouble油耗
speedDouble速度(km/h)
altitudeInteger海拔(米)
isPoweroffBoolean主电源掉电
isAccBooleanACC 状态
isLocationingBoolean卫星定位
isSupplyBoolean补传标志
directionInteger方向(0-360度)
plateNumberString车牌号

6.18 车辆停留信息 - GpsStay (6002)

支持的操作矩阵

操作支持说明
QueryList查询车辆停留信息
QueryDetail同 QueryList
其他不支持其他操作

QueryList 请求参数

{
  "plateNumber": "",
  "stopFlag": 0,
  "startDate": "2025-06-01",
  "endDate": "2025-06-05"
}

请求参数说明:

字段类型必填说明
plateNumberString车牌号,不传则查单位全部车辆
stopFlagInteger停留标志:0-全部;1-停止;2-出行
startDateString查询范围开始日期,格式 yyyy-MM-dd
endDateString查询范围结束日期

QueryList 响应示例

[{
  "recordId": 300001,
  "deviceNum": "GPS001",
  "carId": 40001,
  "stopFlag": true,
  "accFlag": false,
  "beginTime": "2025-06-05T12:00:00",
  "beginMileage": 50000.0,
  "beginLatitude": 26.647,
  "beginLongitude": 106.63,
  "beginAddr": "贵阳市观山湖区",
  "endTime": "2025-06-05T13:30:00",
  "endMileage": 50000.0,
  "endLatitude": 26.647,
  "endLongitude": 106.63,
  "endAddr": "贵阳市观山湖区",
  "plateNumber": "贵A66666"
}]

GnssStopRecord 字段说明:

字段类型说明
recordIdLong记录 ID
deviceNumString设备号
carIdLong车辆 ID
stopFlagBoolean停留标志
accFlagBooleanACC 标志
beginTimeString停留开始时间
beginMileageDouble开始里程
beginLatitudeDouble开始纬度
beginLongitudeDouble开始经度
beginAddrString开始地址
endTimeString停留结束时间
endMileageDouble结束里程
endLatitudeDouble结束纬度
endLongitudeDouble结束经度
endAddrString结束地址
plateNumberString车牌号

7. 调用示例

7.1 Java Demo 运行指南

示例项目位置: zgc-api-demo/ 目录

依赖的第三方库:

库名版本
httpclient4.5.6
fastjson1.2.76

运行方式: 直接执行 DemoMain.main() 方法

配置说明:

private static final String ENT_CODE = "1000130AF4";  // 单位编码(需替换为实际编码)
private static final String API_URL = "http://localhost:8050/oapi";  // API 地址
private static final String AES_KEY = "Gph8J8OjUZncpUL7yle9HQ==";  // AES 密钥(需替换为实际密钥)

7.2 完整的调用代码示例

以下是一个完整的接口调用流程:

import com.alibaba.fastjson.JSONArray;
import com.alibaba.fastjson.JSONObject;
import zgc.api.demo.params.*;
import zgc.api.demo.utils.HttpUtil;

// 1. 构造请求主体
RequestInfo reqInfo = new RequestInfo();
reqInfo.entCode = "1000130AF4";               // 单位编码
reqInfo.intfType = OapiIntfType.UseCarFlow;    // 接口类型
reqInfo.operType = OapiOperType.QueryList;     // 操作类型
reqInfo.enType = OapiEncryptType.None;         // 加密类型

// 2. 构造业务参数
JSONObject reqParams = new JSONObject();
reqParams.put("beginDate", "2025-01-01");
reqParams.put("endDate", "2025-06-05");
reqParams.put("dataStates", "0,10");
reqParams.put("pageIndex", 1);
reqParams.put("pageSize", 10);
reqInfo.data = JSONObject.toJSONString(reqParams);

// 3. 序列化为 JSON 并发送请求
String reqJson = JSONObject.toJSONString(reqInfo);
String retJson = HttpUtil.httpSendJson("http://localhost:8050/oapi", reqJson);

// 4. 解析响应
ReturnInfo retInfo = JSONObject.parseObject(retJson, ReturnInfo.class);
if (retInfo.code != 0) {
    throw new Exception("调用失败:" + retInfo.message);
}

// 5. 处理返回数据
// 非加密情况下直接解析 data
JSONObject dataObj = JSONObject.parseObject(retInfo.data);
int pageIndex = dataObj.getIntValue("pageIndex");
int totalCount = dataObj.getIntValue("totalCount");
JSONArray list = dataObj.getJSONArray("list");

8. 返回码说明

code说明
0成功,data 字段包含业务数据
1业务处理失败,message 字段描述具体错误原因

返回码 1 的常见错误消息

错误消息触发场景
缺少参数请求参数中 entCode、intfType 或 operType 为空
服务端调用出错服务端发生未预期的异常
单位信息不存在未找到对应单位的配置信息
单位编号错误根据 entCode 查询不到单位信息
未开放接口,请联系智管车客服该单位未开通接口权限
接口【xxx-xxx】调用频繁,请调整调用频次!同一接口 30 秒内重复调用
接口 xxx 不支持intfType 不在支持的范围内
方法调用不支持!该接口不支持请求的 operType
接口不支持增加/删除/修改……特定接口对该操作不做支持
参数车牌号为空!GpsRoute 缺少必需参数 plateNumber
车辆信息不存在!车牌号未找到对应车辆
车辆未安装GPS设备!车辆未绑定 GPS 设备号
缺少 use_num 参数QueryDetail 未传入申请单号

9. 常见问题

Q1: 如何获取单位编码(entCode)和密钥?

单位编码由智管车平台统一分配。AES/RSA 密钥在智管车平台后台生成并提供给调用方。请确保企业信息的 oapiEnabled 字段为启用状态。

Q2: 私有化部署支持吗?

OAPI 接口支持私有化部署。私有模型下,需要在智管车配置界面中关闭 IS_PRIVATE_MODEL,OAPI 接口才会生效(参见 OapiHandler.init() 中的判断)。

Q3: 接口返回空数据怎么办?

Q4: 数据加密后如何处理?

如果使用 AES/RSA 加密,请求和响应中的 data 字段均为 Base64 MIME 编码的密文字符串。需要在调用方自行完成:

Q5: 默认返回格式是怎样的?