警备通警用装备管理系统软件接口文档.docx
《警备通警用装备管理系统软件接口文档.docx》由会员分享，可在线阅读，更多相关《警备通警用装备管理系统软件接口文档.docx（16页珍藏版）》请在冰豆网上搜索。
警备通警用装备管理系统软件接口文档
“警备通”警用装备管理系统
接口集成文档
1.接口说明
本技术方案针对“警备通”与其它外部系统业务协作接口的技术实现进行设计。
1.1接口方式
外部系统与“警备通”之间的接口采用HttpWebAPI接口形式来进行业务数据的交互。
接口数据传输采用JSON数据交换格式，数据采用utf-8编码。
考虑到“警备通”的可集成性，要求“警备通”对各个外部系统所提供的接口API及其参数信息、格式均是统一的。
“警备通”与外部系统属于一对多的关系。
1.2接口安全
虽然接口双方都是存在于内部网络中，但是，仍不能排除接口服务被攻击、恶意调用以及非法调用等。
所以，从接口调用上，必须考虑调用的认证安全问题。
本方案中，在客户端调用服务端的时候，必须经过调用身份认证。
本方案采用客户端安全身份认证的方式，即在访问接口所在的服务的时候，都必须进行身份校验（基于Token的令牌验证）。
基于Token的令牌验证方式具有服务端无状态化、可扩展性好、安全、支持跨程序调用等特点，这种方式要求客户端先向服务端请求访问令牌（使用用户名和密码），客户端每次向服务端请求资源时均须携带服务端签发的Token，服务端收到请求，验证客户端Token的合法性，如果验证成功，就向客户端返回请求的数据。
基于token的用户认证是一种服务端无状态的认证方式，服务端不用存放token数据。
用解析token的计算时间换取session的存储空间，从而减轻服务器的压力，减少频繁的查询数据库。
1.3数据格式、约定
客户端和服务端互相之间通讯的请求报文和结果报文遵循JSON格式。
客户端发送请求报文，服务器解析调用报文，执行报文中所在接口对应的服务功能。
生成结果报文，以JSON格式返回给请求者。
请求者拿到结果报文，进行解析，然后再进行相应的处理。
为便于调用双方对数据报文进行统一的解析处理，需对报文的数据格式和规则进行如下约定：
●报文中所有的字典信息（比如性别1-男，2-女），都以代码的值（1或者2）来传递；
●报文中的其他数据类型，比如货币、日期、时间、文件对象等，根据需要转换成文本、数值或二进制（最终转换成Base64字符）的数据类型；
●报文中的日期信息，转换成YYYYMMDDHHmmss文本格式（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.1AccessToken鉴权接口
2.1.1接口定义
Token是服务端的全局唯一接口调用凭据，客户端调用服务端各接口时都需使用，Token的有效期目前为2个小时，需定时刷新，重复获取将导致上次获取的Token失效。
URL
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
本周点验数
升级会员 