开发前必读

published on: 2019-10-20 20:28:40

开发文档阅读说明

  1. 考勤API开放了丰富的能力接口,开发者可以通过API结果获取授权范围内的用户打卡结果信息,打卡流水信息,获取用户所在考勤组信息,排班信息等等。

  2. 开发者在 调用前,需要进行权限的申请,申请地址"考勤管理端"-- "API接入"(注:登陆考勤管理端,需有管理权限,如租户管理员、考勤组管理员等,如无权限,开发者可咨询企业HR),获取AppKey, AppSecret 以及授权的范围。通过AppKey 和AppSecret 进行鉴权访问每个接口,具体加密鉴权说明,见​加密鉴权鉴权方案说明

  3. 所有的接口需使用HTTPS协议、JSON数据格式、 UTF8编码 。接口说明格式如下:

    ` 请求方式 :GET/POST(HTTPS)

    请求地址 :https://time.clockin.biz/attendance/open-api/getPlanInfo

    请求包结构体

    ...

    参数说明

    ...

    返回结果

    ...

    返回参数说明

    ...`

  • 1)  请求方式 ,标明接口调用的HTTP方法,区分HttpGet/HttpPost请求。所有的请求都为https协议。

  • 2)  请求包体/参数说明 ,标明请求参数示例及说明,参数说明包括字段含义、取值范围,开发者在设计数据结构时,应参考该定义范围。

  • 3)  返回结果/参数说明 ,标明返回参数示例及说明。特别留意,所有接口返回包里都有errcode、errmsg。开发者需 根据errcode是否为0判断是否调用成功 (errcode意义请见​全局错误码​ )。而errmsg仅作参考,后续可能会有变动,因此不可作为是否调用成功的判据。

授权权限说明

开发者在开发的过程中,需先到 "考勤管理后台"-- "API接入" 中进行权限申请, 填写 必要的申请信息。注意,权限申请中的部门或个人,在开发者多次的申请中是累加的,如上一次申请通过了部门A, 当前这次申请通过了部门B, 则所拥有的权限为A + B,平台暂时无法做权限缩减处理。开发者申请审批通过之后,才能进行接口的调用。

调用频率限制

出于系统保护的考虑,我们对接口的调用做了频率限制。单个开发者对单个接口的调用为 10次/s.

最佳开发实践说明

API接口请求中需要groupId 或 planId 时, 开发者需优先调用 获取用户打卡结果 接口,获取用户用户的打卡结果,同时获取到用户每天考勤所在的考勤组ID(groupId) 和班次 ID(planId),然后调用对应的接口。