智管车开放接口（OAPI）调用文档

文档版本：v2.3
更新日期：2026-07-08
适用系统：智管车车辆管理平台
版权所有：贵州易迈思数据服务有限公司
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-Type application/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}"
}

请求字段说明：

字段 类型 必填 说明
entCode String 是 单位编码（由智管车平台分配）
intfType OapiIntfType 是 接口数据类型（枚举值或名称）
operType OapiOperType 是 操作类型（枚举值或名称）
enType OapiEncryptType 否 加密类型，默认为 None
data String 否 业务数据 JSON 字符串，如加密则为 Base64 MIME 字符串

2.4 响应格式

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

响应字段说明：

字段 类型 说明
code int 状态码：0-成功，1-失败
message String 提示消息（支持国际化）
data String 返回数据 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 字符串

算法参数：

算法 详细参数
AES AES/ECB/PKCS5Padding，密钥长度 128 位
RSA RSA/ECB/PKCS1Padding，密钥长度 1024 位，支持分段加解密（最大加密 117 字节/最大解密 128 字节）

2.6 调用频率限制

3. 接口数据类型（OapiIntfType）

枚举值 编号 中文说明 所属模块
Enterprise 1000 单位信息 企业组织
Branch 1001 部门信息 企业组织
Role 1002 角色信息 企业组织
User 1003 用户信息 企业组织
CarGroup 2000 车辆分组 车辆/司机/油卡
CarInfo 2001 车辆信息 车辆/司机/油卡
DriverGroup 2010 司机分组 车辆/司机/油卡
DriverInfo 2011 司机信息 车辆/司机/油卡
OilCardGroup 2020 油卡分组 车辆/司机/油卡
OilCardInfo 2021 油卡信息 车辆/司机/油卡
EtcCardGroup 2022 ETC卡分组 车辆/司机/油卡
EtcCardInfo 2023 ETC卡信息 车辆/司机/油卡
UseCarFlow 3000 用车申请流程 流程相关
Charge 4000 费用信息 费用
UseCarRecord 5000 用车登记 用车
GpsRealInfo 6000 车辆实时位置信息 GPS
GpsRoute 6001 车辆行驶轨迹数据 GPS
GpsStay 6002 车辆停留信息 GPS

4. 操作类型（OapiOperType）

枚举值 编号 中文说明
QueryList 1000 查询列表
QueryDetail 1001 查询明细（仅用车流程可用）
Add 2000 增加
Update 3000 更新
UseCarFlowCancel 3001 用车流程作废
UseCarFlowSubmit 3002 用车流程提交
Delete 4000 删除

5. 加密类型（OapiEncryptType）

枚举值 编号 中文说明
None 0 不加密
Rsa 1 RSA 非对称加密
Aes 2 AES 对称加密

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_code String 单位编码
createtime String 创建时间
ent_name String 单位名称
organization_code String 组织机构代码
address String 地址
linkman String 联系人
linkphone String 联系电话
principal String 负责人
principal_phone String 负责人电话
email String 邮箱
web_address String 网址
intro String 简介
ent_user_id String 单位管理员用户 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_id Long 部门 ID
organ_code String 部门编码
organ_name String 部门名称
organ_phone String 部门电话
organ_man String 部门负责人

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_id Long 角色 ID
role_code String 角色编码
role_name String 角色名称

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_id String 用户 ID
user_name String 用户名
organ_id Long 所属部门 ID
role_id Long 角色 ID
headship Integer 职务
create_time String 创建时间
state Integer 状态
mobilephone String 手机号
email String 邮箱
sex Integer 性别
authorize_handon Boolean 是否授权
is_organ_leader Boolean 是否为部门负责人

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_id Long 分组 ID
group_order Integer 排序号
group_name String 分组名称

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",
  "use_state": 1,
  "driver_id": 50001,
  "driver_info": "张三/13800138000"
}]

返回字段说明：

字段 类型 说明
car_id Long 车辆 ID
create_time String 创建时间
group_id Long 分组 ID
plate_number String 车牌号
plate_color Integer 车牌颜色
car_model String 车辆型号
car_level Integer 车辆类型：1-轿车, 2-货车, 3-客车
buy_date String 购买日期
seat_count Integer 座位数
car_state Integer 车辆状态：1-正常, 2-维修, 3-故障, 4-替代, 10-报废, 11-转让
vin_no String 车架号
engine_no String 发动机号
mileage Double 里程
insurance_cycle Integer 保险周期（天）
audit_cycle Integer 年审周期（天）
repair_distance_cycle Integer 保养里程周期
repair_month_cycle Integer 保养月份周期
repair_last_time String 上次保养时间
insurance_last_time String 上次保险时间
audit_last_time String 上次年审时间
insurance_busi_time String 商业险到期时间
insurance_goods_time String 货物险到期时间
insurance_driver_time String 驾驶员险到期时间
repair_last_mileage Double 上次保养里程
device_num String GPS 设备号
use_state Integer 用车状态：1-未出行, 2-申请出行中, 3-出行中
driver_id Long 当前司机 ID
driver_info String 当前司机信息（姓名/电话）

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": "",
  "use_state": 1,
  "car_id": 40001,
  "car_info": "贵A66666"
}]

返回字段说明：

字段 类型 说明
driver_id Long 司机 ID
group_id Long 分组 ID
user_id String 关联用户 ID
create_time String 创建时间
driver_name String 司机姓名
driver_phone String 司机电话
short_phone String 短号
driver_sex Integer 性别：0-未知, 1-男, 2-女
driver_birthday String 出生日期
lic_type String 驾驶证类型
lic_time String 领证时间
driver_state Integer 司机状态：1-正常, 2-请假中, 10-已离职
memo String 备注
use_state Integer 出行状态：1-未出行, 2-申请出行中, 3-出行中
car_id Long 当前驾驶车辆 ID
car_info String 当前驾驶车辆信息

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_id Long 油卡 ID
group_id Long 分组 ID
card_type Integer 卡类型：0-加油卡, 1-电卡, 2-中石油, 3-中石化
card_num String 卡号
current_amount Double 当前余额
card_state Integer 卡状态：0-未启用, 1-启用, 10-作废
bind_type Integer 绑定类型：0-未绑定, 1-绑定车辆, 2-绑定部门, 3-绑定人员
bind_id Long 绑定对象 ID
bind_name String 绑定对象名称
owner_name String 持卡人姓名
owner_phone String 持卡人电话
memo String 备注

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_id Long ETC卡 ID
group_id Long 分组 ID
card_type Integer 卡类型（0=ETC卡）
card_num String ETC卡号
current_amount Double 当前余额
card_state Integer 卡状态：0-未启用, 1-启用, 10-作废
bind_type Integer 绑定类型：0-未绑定, 1-绑定车辆, 2-绑定部门, 3-绑定人员
bind_id Long 绑定对象 ID
bind_name String 绑定对象名称
owner_name String 持卡人姓名
owner_phone String 持卡人电话
memo String 备注

Update 请求参数

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

仅支持变更ETC卡所属分组（group_id）。

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

支持的操作矩阵

操作 支持 说明
QueryList ✅ 分页查询用车流程列表
QueryDetail ✅ 查询用车流程明细（含审批记录和行车记录）
Add ✅ 新增用车申请（dataState=0 待提交）
Update ✅ 修改用车申请（仅 dataState=0/1 可修改）
UseCarFlowCancel ✅ 作废用车申请（仅 dataState≠20/30 可作废；dataState=10 时如已提车则不允许作废）
UseCarFlowSubmit ✅ 提交用车申请（仅 dataState=0/1 可提交）
Delete ✅ 删除用车申请（仅 dataState=0/1 可删除）

QueryList 请求参数

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

请求参数说明：

字段 类型 必填 说明
dateType Integer 否 日期查询类型：0-按创建日期查询（默认）；1-按使用日期查询
beginDate String 否 查询起始日期，格式 yyyy-MM-dd。dateType=0 时为创建开始日期，dateType=1 时为使用开始日期
endDate String 否 查询结束日期，格式 yyyy-MM-dd。dateType=0 时为创建结束日期，dateType=1 时为使用结束日期
dataStates String 否 数据状态，空为全部，逗号分隔多个状态：0-待提交；1-被打回；10-流程中；20-已完成；30-已作废
pageIndex Integer 否 页码，从 1 开始，默认 1
pageSize Integer 否 每页行数，默认 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 字段说明：

字段 类型 说明
useNum String 申请单号
entCode String 单位编码
flowId Long 流程 ID
nodeId Long 节点 ID
dataState Integer 数据状态：0-待提交, 1-被打回, 10-流程中, 20-已完成, 30-已作废
createTime String 申请时间
applyUserid String 申请人 ID
applyUsername String 申请人
applyOrganid Long 所属部门 ID
applyOrganname String 所属部门
applyType Integer 申请类型：0-申请用车, 1-自助用车
useUserid String 用车人 ID
useUsername String 用车人
applyBeginTime String 申请出车时间
applyEndTime String 申请返车时间
startPlace String 起始地
passPlaceInfo String 途经点
targetPlace String 目的地
placeLonLat String 地点经纬度
needDriver Boolean 是否需要司机
peopleNumber Integer 随车人数
carLevel Integer 车辆类型：1-轿车, 2-货车, 3-客车
useType Integer 用车属性：1-申请用车
useReason String 用车事由
customFields String 自定义字段
carId Long 车辆 ID
carInfo String 车辆信息
driverId Long 司机 ID
driverInfo String 司机信息
realBeginTime String 实际出车时间
realEndTime String 实际返车时间
useRecordid Long 用车记录 ID
beginMileage Double 提车时里程
endMileage Double 还车时里程
beginMileageImage String 提车里程照片
endMileageImage String 还车里程照片
sbRecordId Long 记录 ID
nodeName String 当前节点名称
carImage String 车辆图片
nodeType Integer 节点类型
nodeOrder Integer 节点顺序
sameOrgAudit Boolean 是否同部门审批
pickUser Integer 取车人
returnUser Integer 还车人
driverUserId String 司机用户 ID
deviceNum String GPS 设备号
lastRemark String 最近备注

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_id Long 记录 ID
use_num String 申请单号
record_time String 审批时间
record_type Integer 审批类型：0-提交审核, 1-同意, 2-打回到申请, 3-退回上节点, 10-作废
oper_username String 操作人
remark String 审批意见
pre_node_name String 前节点名称
post_node_name String 后节点名称

routeList（行车记录）字段说明：

字段 类型 说明
record_id Long 记录 ID
use_num String 申请单号
begin_time String 出车时间
begin_mileage Double 出车里程
begin_addr String 出车地址
end_time String 还车时间
end_mileage Double 还车里程
end_addr String 还车地址
memo String 备注

Add 请求参数

支持 snake_case 字段命名：

字段 类型 必填 说明
use_userid String 是 用车人 ID
use_username String 否 用车人
use_reason String 是 用车事由
apply_userid String 否 申请人 ID
apply_username String 否 申请人
apply_organid Long 否 所属部门 ID
apply_organname String 否 所属部门
apply_begin_time String 否 申请出车时间，格式 yyyy-MM-dd HH:mm:ss
apply_end_time String 否 申请返车时间，格式 yyyy-MM-dd HH:mm:ss
start_place String 否 起始地
target_place String 否 目的地
place_lon_lat String 否 地点经纬度
people_number Integer 否 随车人数
need_driver Boolean 否 是否需要司机
car_level Integer 否 车辆类型：1-轿车, 2-货车, 3-客车
use_type Integer 否 用车属性：1-申请用车
car_id Long 否 车辆 ID
car_info String 否 车辆信息
driver_id Long 否 司机 ID
driver_info String 否 司机信息
custom_fields String 否 自定义字段 JSON
flow_id Long 否 流程 ID（不传则使用默认流程）
apply_type Integer 否 申请类型：0-申请用车, 1-自助用车

use_num 由系统自动生成（格式：yyMMddHHmmss + 6位序号），无需传入。dataState 初始为 0（待提交）。

Add 自动提交参数（可选）

在 Add 请求中可通过 submit_info 对象实现新增后自动提交：

{
  "use_userid": "U001",
  "use_reason": "拜访客户",
  "submit_info": {
    "need_submit": true,
    "submit_mileage": 50000.0
  }
}
字段 类型 必填 说明
submit_info.need_submit Boolean 否 是否自动提交，true 则在新增后自动调用提交流程
submit_info.submit_mileage Double 否 提交时的里程数

自动提交等同于新增成功后立即以申请人身份调用 UseCarFlowSubmit 操作。

Add 响应示例

{
  "use_num": "250611093012000001"
}

Update 请求参数

字段 类型 必填 说明
use_num String 是 申请单号
其余字段同 Add，按需传入，仅传入需要修改的字段

修改限制：仅 dataState 为 0（待提交）或 1（被打回）时允许修改。

UseCarFlowCancel 请求参数

{
  "use_num": "YC20250605001"
}

作废限制：仅 dataState 不为 20（已完成）或 30（已作废）时允许作废。此外，当 dataState=10（流程中）时，如果已提车（存在 recordType=3 的流程记录），则不允许作废。

UseCarFlowSubmit 请求参数

{
  "use_num": "YC20250605001",
  "submit_mileage": 50000.0
}

请求参数说明：

字段 类型 必填 说明
use_num String 是 申请单号
submit_mileage Double 否 提交时的里程数

提交限制：仅 dataState 为 0（待提交）或 1（被打回）时允许提交。提交时以申请人身份自动推进流程。

Delete 请求参数

{
  "use_num": "YC20250605001"
}

删除限制：仅 dataState 为 0（待提交）或 1（被打回）时允许删除。

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
}

请求参数说明：

字段 类型 必填 说明
beginDate String 否 查询起始日期，格式 yyyy-MM-dd
endDate String 否 查询结束日期，格式 yyyy-MM-dd
dataState Integer 否 数据状态：-1-全部；-2-已提交和存档的；-3-草稿和打回的（含加油打回）；0-草稿；1-已提交；10-已存档；20-打回的
pageIndex Integer 否 页码，从 1 开始，默认 1
pageSize Integer 否 每页行数，默认 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 字段说明：

字段 类型 说明
entCode String 单位编码
recordId Long 记录 ID
plateNumber String 车牌号
state Integer 状态：0-草稿, 1-已提交, 10-已存档, 20-打回
createTime String 录入时间
operUserId String 录入人 ID
operUserName String 录入人
carId Long 车辆 ID
reviewTime String 审核时间
auditUserName String 审核人
auditReason String 审核意见
driverId Long 司机 ID
useRecordId Long 用车记录 ID
amount Double 金额
beginDate String 费用发生时间
chargeLink Boolean 是否关联费用
linkRecordType Integer 关联类型
driverInfo String 司机信息
userId String 用户 ID
chargeType Integer 费用类别（见下方说明）
oilCardId Long 油卡 ID
userName String 用车人
memo String 备注
linkRecordId String 关联 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 字段说明）：

字段 类型 说明
entCode String 单位编码
recordId Long 记录 ID
plateNumber String 车牌号
state Integer 状态：0-草稿, 1-已提交, 10-已存档, 20-打回
createTime String 录入时间
operUserId String 录入人 ID
operUserName String 录入人
carId Long 车辆 ID
useRecordId Long 用车记录 ID
driverId Long 司机 ID
beginDate String 加油/电时间
oilType String 加油/电型号
oilEnt String 加油电站
oilAmount Double 金额
unitPrice Double 单价
odographCount Double 加油电时公里数
driverInfo String 司机
oilCardId Long 油卡 ID
oilCardNum String 油卡卡号
userName String 用车人
memo String 备注
userId String 用车人 ID

6.15 用车登记 - UseCarRecord (5000)

支持的操作矩阵

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

QueryList 请求参数

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

请求参数说明：

字段 类型 必填 说明
beginDate String 否 查询起始日期，格式 yyyy-MM-dd
endDate String 否 查询结束日期，格式 yyyy-MM-dd
dataState Integer 否 数据状态：-1-全部；-2-已收车和存档的；-3-出车中和打回的；0-出车中；1-已收车；10-已存档；20-打回
pageIndex Integer 否 页码，从 1 开始，默认 1
pageSize Integer 否 每页行数，默认 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": "",
      "state": 0
    }
  ]
}

BookUseRecord 字段说明：

字段 类型 说明
beginDate String 用车时间
beginMileage Double 出车里程
useReason String 用车事由
useName String 用车人/单位
usePhone String 用车人电话
useUserId String 用车人用户 ID
startPlace String 出发地
targetPlace String 目的地
driverInfo String 驾驶员
driverPhone String 驾驶员电话
driverId Long 驾驶员 ID
followMan String 跟车员
followPhone String 跟车员电话
followId Long 跟车员 ID
followIsDriver Boolean 跟车员是司机
useOrganName String 用车部门
useOrganId Long 用车部门 ID
beginCustomFields String 出车自定义字段
endDate String 收车时间
endMileage Double 收车里程
memo String 备注
endCustomFields String 收车自定义字段
state Integer 状态：0-出车中, 1-已收车, 10-已存档, 20-打回

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

支持的操作矩阵

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

QueryList 请求参数

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

请求参数说明：

字段 类型 必填 说明
groupId Long 否 车辆分组 ID，传 0 则忽略条件
plateNumber String 否 车牌号，传空则查单位全部车辆
state Integer 否 行驶状态：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 字段说明：

字段 类型 说明
deviceNum String 设备号
carId Long 车辆 ID
lastState Integer 行驶状态：0-离线；1-行驶；2-停留
lastTime String 最后定位时间
validTime String 有效时间
posLatitude Double 纬度
posLongitude Double 经度
mileage Double 里程（km）
fuelConsumption Double 油耗
speed Double 速度（km/h）
altitude Integer 海拔（米）
isAcc Boolean ACC 状态
isLocationing Boolean 是否卫星定位
isSupply Boolean 是否补传
direction Integer 方向（0-360度）
isPoweroff Boolean 主电源是否掉电
lastPosId Long 最后位置 ID
lastAccId Long 最后 ACC ID
plateNumber String 车牌号
groupId Long 分组 ID
useNum String 用车申请编号
posAddr String 位置地址描述

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"
}

请求参数说明：

字段 类型 必填 说明
plateNumber String 是 车牌号（必需传入）
useNum String 否 用车申请编号
startTime String 否 查询范围开始时间，格式 yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss
endTime String 否 查询范围结束时间

注意：一次查询最多返回 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 字段说明：

字段 类型 说明
posId Long 位置 ID
deviceNum String 设备号
carId Long 车辆 ID
useNum String 用车申请编号
createTime String 定位时间
posLatitude Double 纬度
posLongitude Double 经度
mileage Double 里程（km）
fuelConsumption Double 油耗
speed Double 速度（km/h）
altitude Integer 海拔（米）
isPoweroff Boolean 主电源掉电
isAcc Boolean ACC 状态
isLocationing Boolean 卫星定位
isSupply Boolean 补传标志
direction Integer 方向（0-360度）
plateNumber String 车牌号

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

支持的操作矩阵

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

QueryList 请求参数

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

请求参数说明：

字段 类型 必填 说明
plateNumber String 否 车牌号，不传则查单位全部车辆
stopFlag Integer 否 停留标志：0-全部；1-停止；2-出行
startDate String 否 查询范围开始日期，格式 yyyy-MM-dd
endDate String 否 查询范围结束日期

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 字段说明：

字段 类型 说明
recordId Long 记录 ID
deviceNum String 设备号
carId Long 车辆 ID
stopFlag Boolean 停留标志
accFlag Boolean ACC 标志
beginTime String 停留开始时间
beginMileage Double 开始里程
beginLatitude Double 开始纬度
beginLongitude Double 开始经度
beginAddr String 开始地址
endTime String 停留结束时间
endMileage Double 结束里程
endLatitude Double 结束纬度
endLongitude Double 结束经度
endAddr String 结束地址
plateNumber String 车牌号

7. 调用示例

7.1 Java Demo 运行指南

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

依赖的第三方库：

库名 版本
httpclient 4.5.6
fastjson 1.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: 默认返回格式是怎样的？