服务开发说明

轻应用是APP NEST为连接企业办公打造的移动入口,通过轻应用你可以将企业的业务审批,内部OA,CRM,协作等移动应用发布到APP NEST门户客户端,更简单和低成本实现企业移动化; 结合APP NEST门户客户端的基础通信能力,让企业应用更活跃,员工更高效,移动化成本更低。

此文档很适合于:

  • 企业的IT部,了解APP NEST如何连接你所在企业的办公;
  • 应用开发商,了解如何通过APP NEST为您的客户提供定制的企业办公软件,提升你的服务价值。

1. 轻应用与APP NEST集成

企业应用服务器调用APP NEST开放平台提供的接口,以轻应用的身份给企业用户的账号推送消息,以下称主动调用模式;

用户在门户客户端使用轻应用H5页面时,该页面可以调用门户客户端提供的JS接口,使用门户客户端开放的终端能力和业务能力,以下称 JSAPI模式

APP NEST服务器把用户发送的消息或用户触发的事件推送给企业应用,由企业应用处理,以下称回调模式。

1.1 主动调用

当企业应用服务器调用开放平台接口时,需使用http协议、Json数据格式、UTF8编码。应用服务在每次主动调用开放平台接口时需要带上APPKey和APPSecret参数。APPKey和APPSecret为在开发者平台创建的当前应用的应用标识。

2. 主动调用方式

当获取到APPKey、APPSecret以及AccessToken时,轻应用后台就可以成功调用APP NEST后台所提供的各种接口、或访问相应企业的资源、或给微应推送消息。APPKey和APPSecret的获取前面已经介绍,AccessToken的获取主要有两种获取方式:

  • 轻应用在门户客户端认证通过后,从门户中获取到AccessToken,以后轻应用在调用后台服务的时候,可以将这个参数传输给后台服务,后台服务可以拿这个参数以及APPKey和APPSecret调用开放平台接口;
  • 管理平台跳转到轻应用管理平台时,携带AccessToken给轻应用管理平台,轻应用管理平台获得这个参数之后,同时携带APPKey和APPSecret回调管理平台的开放接口获取管理员个人信息;

每个开放平台接口都做了异常处理,会根据不同的异常情况返回相应的错误码。

1.3  错误码列表

每个开放平台接口都做了异常处理,会根据不同的异常情况返回相应的错误码。

表一 开放平台错误码列表

错误码 描述
100 服务无法响应
101 服务请求超时
102 请求内容格式不正确
103 请求方法不存在
104 请求服务不存在
105 服务已经过期
106 服务必须通过SSL方式请求
107 服务必须通过指定的加密算法
108 不能识别的客户端应用
109 客户端未被激活(无效的请求客户端)
110 无效的报文签名
111 不支持的签名算法
112 方法内部异常
113 错误的请求参数
114 服务要求登录
115 请求被拒绝,注册器中仅有empty协议数据(原启动的服务已经全部停掉)
116 请求内容不合法
120 解压缩过程失败
121 不被支持的压缩算法
122 压缩过程失败
123 非法的客户端
124 响应报文不合法
125 响应报文签名异常
126 应用未激活
127 未知封装异常
128 请求时间与服务器时间差距超过5分钟
129 未知的协议封装异常
130 响应格式化异常
131 无效的客户端
200 请求异常
201 服务驱动异常
203 内部网络异常
204 内部序列化异常
205 内部响应异常
206 未知的RPC异常
300 权限不足
301 请求大小超限
301 同一个AppKey请求超限
302 请求会话过程超限
303 服务请求次数超限
304 服务调用频率超限

2. 用户中心

2.1 获取用户详情

请求地址:http://Open_ip:Open_port/nqsky-meap-open-webapps

方法名:getUserInfo

所属服务组名:用户操作

返回类型:UserInfo

参数说明:

名称 类型 是否必须 描述
userId String 用户唯一标识ID

2.2 获取成员列表

请求地址:http://Open_ip:Open_port/nqsky-meap-open-webapps

方法名:findUserInfoList

所属服务组名:用户操作

返回类型:UserInfoList

参数说明:

名称 类型 是否必须 描述
offset String 查询起始位置
length String 查询起始位置

2.3  根据用户id删除用户

方法名:deleteUserInfoById

所属服务组名:用户操作

返回类型:Boolean

参数说明:

名称 类型 是否必须 描述
userId String 用户唯一标识ID

2.4 创建或更新用户信息

方法名:saveOrUpdateUserInfo

所属服务组名:用户操作

返回类型:UserInfo

参数说明:

名称 类型 是否必须 描述
account String
agencyJobList String

2.5 获取部门列表

方法名:findAgencyInfoList

所属服务组名:部门操作

返回类型:AgencyInfoList

参数说明:

名称 类型 是否必须 描述
offset String 查询起始位置
length String 单次查询数量(分页缓存)

2.6 创建或更新部门信息

方法名:saveOrUpdateAgency

所属服务组名:部门操作

返回类型:AgencyInfo

参数说明:

名称 类型 是否必须 描述
agency String 请求参数

2.7 根据部门id删除部门

方法名:deleteAgencyInfoById

所属服务组名:部门操作

返回类型:Boolean

参数说明:

名称 类型 是否必须 描述
agencyId String 部门id

2.8  获取部门信息

方法名:getAgencyInfo

所属服务组名:部门操作

返回类型:AgencyInfo

参数说明:

名称 类型 是否必须 描述
agencyId String 部门id

2.9 获取部门直属人员信息

方法名:getAgencyUserInfo

所属服务组名:部门操作

返回类型:AgencyUserInfo

参数说明:

名称 类型 是否必须 描述
agencyId String 部门id

2.10  根据职位和部门获取人员

方法名:getUserInfoByJobName

所属服务组名:用户操作

返回类型:AgencyUserInfo

参数说明:

名称 类型 是否必须 描述
agencyId String 部门id
jobName String 职位名称

2.11 用户登录

方法名:userLogin

所属服务组名:用户操作

返回类型:UserInfo

参数说明:

名称 类型 是否必须 描述
userName String 登陆名
password String 登陆密码

3. 消息推送

APP NEST产品已打通服务端到客户端的消息推送通道,并将这条通道以开放性的服务提供出来,供应用开发者调用。

调用者通过调用此服务,可以实现将消息以通知形式主动推送到门户客户端。门户客户端根据后台的参数来进行通知提醒,同时将消息汇聚到门户客户端消息模块中的通知列表中。用户点击手机通知栏内的通知,或者点击消息列表中的消息,则直接跳转到应用的详情页面中。

服务端提供开放的消息推送接口供第三方轻应用服务调用。

接口名:com.nqsky.meap.api.basic.open.IMessageOpenApi

方法名:sendMessage

所属服务组名:推送服务

返回类型:Boolean

参数说明:

名称 类型 是否必须 描述
module String 模块名称
msgType String 消息类型
title String 消息标题
summary String 消息摘要
msgUrl String 消息链接
msgImage String 消息图片上传到fstp对应的fileToken
content String 消息内容
topic String appFlag轻应用标识(N/A或空,默认为门户)
code Int 消息代码
expireddays Int 消息过期天数,可设置默认值。在onlyPush为false时,可以在有效期内同步指令通知内容
onlyPush Boolean 是否只推送。true不记录在消息盒子中;false记录,可以同步
tokenType String 推送|发送方式,目前主要使用USER|USER_GROUP|ALL_USER
token String 推送方式对应内容,如用户账号、用户标签/用户分组,多个用,分隔。发ALL_USER时,该参数可以不传或传空 (USER/USER_GRPUP必填, ALL_USER,不传)

4. 服务端免登服务集成

接口实现功能:第三方应用要想实现与门户管理平台或者门户服务的统一认证集成,可集成免登服务来实现。

第三方应用提供链接入口,该入口会接收到管理平台的调用请求,管理平台将当前AccessToken传递给该入口,入口拿到AccessToken后调用免登接口,该接口验证AccessToken的合法性,同时返回用户信息及会话时长;当会话超时或AccessToken验证失败,第三方应用应跳转到指定错误页面提示重新登录。

接口名:com.nqsky.meap.api.sso.open.ISsoOpenService

方法名:getUserInfo

所属服务组名:统一认证

返回类型:UserInfo

参数说明:

名称 类型 是否必须 描述
ssoTicket String 查询参数

5. 文件中心集成

接口实现功能:APP NEST开放平台提供文件处理类服务,主要是文件上传服务,通过文件上传服务实现文件上传。

接口名:com.nqsky.meap.api.fstp.open.IFstpOpenApi

方法名:uploadFile

所属服务组名:文件服务

返回类型:String (FileToken)

参数说明:

名称 类型 是否必须 描述
file FileItem FileItem类型

  • 图片(image):1MB,支持JPG格式
  • 语音(voice):2MB,播放长度不超过60s,AMR格式
  • 普通文件(file):10MB

6. 标签操作类

6.1 获取用户所属标签

接口实现功能:APPENEST开放平台提供用户标签的查询接口,通过用户标签可以替代用户角色的权限功能,利用标签实现权限的统一分配或用户身份的标识。

接口名:com.nqsky.meap.api.user.open.IUserTagUserOpenService

方法名:findUserTagUserList

所属服务组名:标签服务

返回类型:UserTagUserInfo

参数说明:

名称 类型 是否必须 描述
userAccountId String 请求参数

6.2 获取所有标签

接口名:com.nqsky.meap.api.user.open.IUserTagOpenService

方法名:userLogin

所属服务组名:标签服务

返回类型:UserTagInfo

参数说明:无