“警备通”警用装备管理系统软件接口文档

“警备通”警用装备管理系统
接口集成文档
1.接口说明
本技术方案针对“警备通”与其它外部系统业务协作接口的技术实现进行设计。

1.1接口方式
外部系统与“警备通”之间的接口采用Http Web API接口形式来进行业务数据的交互。

接口数据传输采用JSON数据交换格式，数据采用utf-8编码。

考虑到“警备通”的可集成性，要求“警备通”对各个外部系统所提供的接口API及其参数信息、格式均是统一的。

“警备通”与外部系统属于一对多的关系。

1.2接口安全
虽然接口双方都是存在于内部网络中，但是，仍不能排除接口服务被攻击、恶意调用以及非法调用等。

所以，从接口调用上，必须考虑调用的认证安全问题。

本方案中，在客户端调用服务端的时候，必须经过调用身份认证。

本方案采用客户端安全身份认证的方式，即在访问接口所在的服务的时候，都必须进行身份校验（基于Token的令牌验证）。

基于Token的令牌验证方式具有服务端无状态化、可扩展性好、安全、支持跨程序调用等特点，这种方式要求客户端先向服务端请求访问令牌（使用用户名和密码），客户端每次向服务端请求资源时均须携带服务端签发的 Token，服务端收到请求，验证客户端Token的合法性，如果验证成功，就向客户端返回请求的数据。

基于 token 的用户认证是一种服务端无状态的认证方式，服务端不用存放token 数据。

用解析 token 的计算时间换取 session 的存储空间，从而减轻服务器的压力，减少频繁的查询数据库。

1.3数据格式、约定
客户端和服务端互相之间通讯的请求报文和结果报文遵循JSON格式。

客户端发送请求报文，服务器解析调用报文，执行报文中所在接口对应的服务功能。

生成结果报文，以JSON格式返回给请求者。

请求者拿到结果报文，进行解析，然后再进行相应的处理。

为便于调用双方对数据报文进行统一的解析处理，需对报文的数据格式和规则进行如下约定：
●报文中所有的字典信息（比如性别1-男，2-女），都以代码的值（1或者2）
来传递；
●报文中的其他数据类型，比如货币、日期、时间、文件对象等，根据需要转
换成文本、数值或二进制（最终转换成Base64字符）的数据类型；
●报文中的日期信息，转换成YYYYMMDD HHmmss文本格式（24小时制）。

如果
是空日期，则转换成空文本；
●报文中的true和false数据类型，转换成 0(表示false)、1（表示true）；
●报文中的二进制数据（如文件对象），转换成Base64字符方式发送；
●如果返回结果数据集非常多，在性能考虑和数据量冲突的情况下，可以使用
分页返回数据集的方式分批返回数据（每次返回最多100条记录）。

服务端提供分批结果返回的功能。

1.4容错处理
客户端向服务端发送数据，服务端解析数据，反馈信息给客户端，这中间的环节只要某一个环节出现问题，都会造成接口的失败。

按照失败产生的环节分类，
我们可以从三个方面来处理接口的失败。

●网络连接失败：在调用接口的时候，由于网络不通，造成数据不能正常传输。

这样，客户端应该能够记录发送的日志，按照一定的时间间隔重试发送。

本方案定为重试发送20次，每次时间间隔2小时。

如果一直发生网络不通的情况，该发送日志被保存下来，待后手工发送。

所以，客户端系统应该实现手工发送数据的功能。

●反馈错误信息：服务端在解析数据包，执行数据包业务的时候，可能会发生
异常。

所以，服务端应当能够捕捉异常信息，比如“非法XML格式”等，然后反馈给客户端。

客户端在接受到这类的错误信息之后，应当进行日志记录，能够自动或手工分析异常的信息。

●网络连接正常，但是无信息反馈：这种情况下，一般是服务端出现了异常，
但是又没有捕捉到的情况下发生。

这种情况下，客户端把这种错误当作“网络连接失败”来处理。

服务端应能够实现相同数据包重新发送过来的处理机制。

1.5通用错误返回码
返回码表示说明
200 请求正常
401 Token鉴权失败获取Token令牌时，验证用户名密码失败403 Token验证失败执行接口请求时，Token不存在或失效
405 参数校验失败执行接口请求时，出现参数缺失、格式错误2.接口定义
2.1Access Token鉴权接口
2.1.1接口定义
Token是服务端的全局唯一接口调用凭据，客户端调用服务端各接口时都需使用，Token的有效期目前为2个小时，需定时刷新，重复获取将导致上次获取的Token失效。

UR L http://*****/webapi/token?username={username}&password={password }
协
议
http
请
求
方
式
GET/POST
2.1.2参数说明
参数名称是否必须类型描述
username 必选String 第三方用户唯一凭证password 必选String 第三方用户唯一凭证密钥2.1.3返回结果
正常情况下，服务端会返回下述JSON数据包给客户端：
{"access_token":"ACCESS_TOKEN","expires_in":7200}
参数说明：
参数名称描述
access_token 获取到的令牌凭证
expires_in 凭证有效时间，单位：秒
2.2装备库存明细查询接口
2.2.1接口定义
该接口由“警备通”提供，用于外部系统调取设备数据。

URL http://*****/webapi/equitment/inventory
协议http
请求方式GET
2.2.2参数说明
参数名称是否必须类型描述
token 必选String 通过获取鉴权Token接口返回warehouseId 必选String 所属装备室
offset 必选int 分页起始位置
size 选填int 每页查询数量，大于100时按
100条返回
2.2.3返回结果
响应参数说明：
参数名称描述
code 错误码,200代表成功
message 错误信息
equitments 数组类型，装备列表
equitmentName 装备名称
warehouseName装备室名称
equitmentNo 装备编号
equitmentType 装备分类
brand 装备品牌
specification 装备规格型号
prescribedQuan 装备规定数量
totalStorage 装备总入库量
totalOut 装备总出库量
remaining 装备剩余库存
maintenance 装备保养周期
check 装备点验周期
position 装备存储位置
price 装备价格
totalScrap 总处置数
2.3个人持有明细接口查询
2.3.1接口定义
该接口由“警备通”提供，用于外部系统调取设备数据。

URL http://*****/webapi/equitment/personal
协议http
请求方式GET
2.3.2参数说明
参数名称是否必须类型描述
token 必选String 通过获取鉴权Token接口返回warehouseId 必选String 所属装备室
userId 选填String 所属警员
offset 必选int 分页起始位置
size 选填int 每页查询数量，大于100时按
100条返回
2.3.3返回结果
响应参数说明：
参数名称描述
code 错误码,200代表成功
message 错误信息
equitments 数组类型，装备列表
equitmentName 装备名称
equitmentNo 装备编号
userId装备持有人
holdingTime 持有时间
purchaseTime 购置时间
price 购置价格
expiration 过期时间
equipmentStatus 装备状态
lastmaintenanceTime 最后维护时间
2.4装备入库明细接口查询
2.4.1接口定义
该接口由“警备通”提供，用于外部系统调取装备入库明细数据。

URL http://*****/webapi/equitment/warehousing
协议http
请求方式GET
2.4.2参数说明
参数名称是否必须类型描述
token 必选String 通过获取鉴权Token接口返回warehouseId 必选String 所属装备室
offset 必选int 分页起始位置
size 选填int 每页查询数量，大于100时按
100条返回
2.4.3返回结果
响应参数说明：
参数名称描述
code 错误码,200代表成功
message 错误信息
equitments 数组类型，装备列表
warehouseName装备室名称
equitmentName 装备名称
equitmentNo 装备编号
purchaseTime 购置时间
price 购置价格
usageTime 使用年限
expiration 过期时间
statusUse 使用状态
equipmentStatus 装备状态
manager 经办人
storageTime 入库日期
2.5装备领用明细接口查询
2.5.1接口定义
该接口由“警备通”提供，用于外部系统调取装备领用明细数据。

URL http://*****/webapi/equitment/receiving
协议http
请求方式GET
2.5.2参数说明
参数名称是否必须类型描述
token 必选String 通过获取鉴权Token接口返回warehouseId 必选String 所属装备室
offset 必选int 分页起始位置
size 选填int 每页查询数量，大于100时按
100条返回
2.5.3返回结果
响应参数说明：
参数名称描述
code 错误码,200代表成功
message 错误信息
equitments 数组类型，装备列表
warehouseId 所属装备室
warehouseName装备室名称
equitmentName 装备名称
equitmentNo 装备编号
employer 领用人
reasonsAdoption 领用缘由
returnStatus 归还状态
returnee 归还人
returnTime 归还时间
manager 经办人
takeTime 领用时间
2.6装备交接明细接口查询
2.6.1接口定义
该接口由“警备通”提供，用于外部系统调取装备交接明细数据。

URL http://*****/webapi/equitment/handover
协议http
请求方式GET
2.6.2参数说明
参数名称是否必须类型描述
token 必选String 通过获取鉴权Token接口返回warehouseId 必选String 所属装备室
offset 必选int 分页起始位置
size 选填int 每页查询数量，大于100时按
100条返回
2.6.3返回结果
响应参数说明：
参数名称描述
code 错误码,200代表成功
message 错误信息
equitments 数组类型，装备列表
equitmentName 装备名称
equitmentNo 装备编号
deliverer 交付人
delivererUnit 交付人单位
receiver 接收人
recipientUnit 接收人单位
reasonHandover 交接原因
handoverDate 交接日期
2.7装备点验明细接口查询
2.7.1接口定义
该接口由“警备通”提供，用于外部系统调取装备点验明细数据。

URL http://*****/webapi/equitment/check
协议http
请求方式GET
2.7.2参数说明
参数名称是否必须类型描述
token 必选String 通过获取鉴权Token接口返回warehouseId 必选String 所属装备室
offset 必选int 分页起始位置
size 选填int 每页查询数量，大于100时按
100条返回
2.7.3返回结果
响应参数说明：
参数名称描述
code 错误码,200代表成功
message 错误信息
equitments 数组类型，装备列表
warehouseName 装备室名称
equitmentName 装备名称
checkNo 点验数
checkPerson 点验人
checkContent 点验内容
checkDate 点验日期
manager 经办人
2.8装备维护明细接口查询
2.8.1接口定义
该接口由“警备通”提供，用于外部系统调取装备维护明细数据。

URL http://*****/webapi/equitment/maintain
协议http
请求方式GET
2.8.2参数说明
参数名称是否必须类型描述
token 必选String 通过获取鉴权Token接口返回warehouseId 必选String 所属装备室
offset 必选int 分页起始位置
size 选填int 每页查询数量，大于100时按
100条返回
2.8.3返回结果
响应参数说明：
参数名称描述
code 错误码,200代表成功
message 错误信息
equitments 数组类型，装备列表
equitmentName 装备名称
equitmentNo 装备编号
approver 批准人
maintenance 维护人
maintenanceContent 维护内容
maintenanceDate 维护日期
2.9装备处置明细接口查询
2.9.1接口定义
该接口由“警备通”提供，用于外部系统调取装备维处置明细数据。

URL http://*****/webapi/equitment/dispose
协议http
请求方式GET
2.9.2参数说明
参数名称是否必须类型描述
token 必选String 通过获取鉴权Token接口返回warehouseId 必选String 所属装备室
offset 必选int 分页起始位置
size 选填int 每页查询数量，大于100时按
100条返回
2.9.3返回结果
响应参数说明：
参数名称描述
code 错误码,200代表成功
message 错误信息
equitments 数组类型，装备列表
warehouseId 所属装备室
equitmentName 装备名称
equitmentNo 装备编号
purchaseTime 购置日期
serviceLife 使用年限
expiration 过期日期
reasonScrap 报废原因
disposalMethod 处置方式
disposalDate 处置日期
manager 经办人
2.10数据摘要查询接口
2.10.1接口定义
该接口由“警备通”提供，用于外部系统调取装备数据摘要信息。

URL http://*****/webapi/dataSummary
协议http
请求方式GET
2.10.2参数说明
参数名称是否必须类型描述
token 必选String 通过获取鉴权Token接口返回warehouseId 必选String 所属装备室
2.10.3返回结果
响应参数说明：
参数名称描述
code 错误码,200代表成功
message 错误信息totalEquipment 总装备数equipmentClass 装备分类数storageToday 今日入库数outboundToday 今日出库数maintenanceToday 今日维护数checkToday 今日点验数storageWeek 本周入库数outboundWeek 本周出库数maintenanceWeek 本周维护数checkWeek 本周点验数。