使用说明 | API开放平台

# 使用说明

勤策系统为了支持将企业外部各个系统（后面统称为第三方系统）集成到勤策APP菜单中，勤策APP提供了一系列扩展接口允许第三方系统使用勤策APP的手机能力，如：拍照、定位等。本章主要介绍第三方系统应用在集成到勤策APP中时，如何嵌入JS并调用各个JSAPI，以及各个API的详细信息。以便获取需要的数据和文件。

为了便于后续开发的展开，需要企业管理员和第三方开发者提前做好一些准备操作。

1.申请对接第三方应用APPID，申请第三方应用APPID需要提供应用名称、应用图标、应用信任域名。当前管理员需要联系勤策客成经理操作，申请流程具体步骤详见（申请第三方应用APPID (opens new window)），申请完成后会获取到应用的配置信息：appId(应用ID), appSecret(应用秘钥), tenantId(企业ID)。

2.创建内嵌到勤策的菜单，管理员需要根据业务要求，需要提供菜单URL，菜单名称，菜单所在目录。注意菜单URL所在域名要和1中申请的应用信任域名一致，如：https://www.yourcompany.com/test.html。

3.第三方服务端需要根据引导获取AccessToken (opens new window)和JSSDK ticket (opens new window)，用于取得第三方应用调用勤策APP能力授权。

# 关键词

关键词	说明
`tenantId`	企业ID，对接的企业唯一标识，企业开户时确定。
`appId`	应用ID，用来区分接入的第三方系统是来自哪个系统，每个应用只能有一个可信任域名。
`appSecret`	应用秘钥，用于服务器生成该企业接入勤策系统的应用唯一的授权访问令牌AccessToken，这个秘钥要注意保存，不可以放前端页面。
`timestamp`	时间戳，是从1970年1月1日（UTC/GMT的午夜）开始所经过的秒数（不考虑闰秒），用于表示一个时间点，用于应用授权验证。
`nonceStr`	随机6-16位字符串，用于生成加签名信息。
`signature`	JS-SDK鉴权签名信息，使用勤策规定签名算法生成的签名信息，用于勤策访问安全校验。附录-JS-SDK使用权限签名算法 (opens new window)
`jsApiList`	需要申请使用的JSAPI接口列表，如：getLocation，uploadImage等。

# 开始接入JS-SDK

步骤一：引入JS文件

在需要调用JS接口的页面引入如下JS文件，（支持https）：http://res.waiqin365.com/p/open/js/waiqin365.min.js

步骤二：通过config接口注入权限验证配置

所有需要使用JS-SDK的页面必须先注入配置信息，否则将无法调用

wq.config({
  appId: '', // 必填，应用Id
  timestamp: , // 必填，生成签名的时间戳
  nonceStr: '', // 必填，生成签名的随机串
  signature: '',// 必填，签名，见 附录-JS-SDK使用权限签名算法
  jsApiList: [] // 必填，需要使用的JS接口列表，凡是要调用的接口都需要传进来
});

步骤三：通过ready接口处理成功验证

wq.ready(function(){
  // config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异步操作，所以如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中。
});

步骤四：通过error接口处理失败验证

wq.error(function(res){
  // config信息验证失败会执行error函数，如签名过期导致验证失败，具体错误信息可以打开config的debug模式查看，也可以在返回的res参数中查看，对于SPA可以在这里更新签名。
});

接口调用说明

所有接口通过wq对象来调用，参数是一个对象，除了每个接口本身需要传的参数之外，还有以下通用参数：

success：接口调用成功时执行的回调函数。 fail：接口调用失败时执行的回调函数。 complete：接口调用完成时执行的回调函数，无论成功或失败都会执行。 cancel：用户点击取消时的回调函数，仅部分有用户取消操作的api才会用到。

以上几个函数都带有一个参数，类型为对象，其中除了每个接口本身返回的数据之外，还有一个通用属性errMsg，其值格式如下：

1、调用成功时：”xxx:ok” ，其中xxx为调用的接口名

2、用户取消时：”xxx:cancel”，其中xxx为调用的接口名

3、调用失败时：其值为具体错误信息

← 概述基础接口 →