引言

欢迎使用知人的应用编程接口 API v2.0 通过 API 您可以接入知人提供的大部分服务。

知人 API v2.0 遵循 RESTful 风格，所有 API 的 URL 都是

https://zhiren.com/api/v2/<apiname>

1. 请求中的业务数据以 JSON 格式传递，认证数据则以 URL 查询参数的形式传递。
2. 响应以 HTTP Status Code 来表示成功（2xx）或失败，如果失败，则会在响应体中以 JSON 格式给出详细的错误信息。

认证

知人第三方服务称为 Product，通过 API 请求知人时，每一个需要验证的请求都要进行签名。

Product 对应每个 Company 都有唯一的 access_key 与 secret_key 。

Parameters

access_key

访问识别码，当您成为知人第三方服务，对应每个开通服务的公司，都会有一对 access_key 和 secret_key, 其中 access_key 必须在每次请求中附上，而 secret_key 请务必放在私有的空间，千万不可在请求中传递。

signature

使用你的 secret_key 进行签名后的字符串，放入 header 的自定义字段 x-zhiren-signature

tonce

请求时间, 必须以 Unix Time 的格式发送, tonce与服务器时间不得超过正负 5 分钟, 否则请求将视为无效。

payload

被签名的数据体部分，JSON 格式的字符串。

signature 的算法

我们用伪代码表示签名的算法如下：

signature = HMAC-SHA256( secret_key, string_to_sign )

首先根据请求的参数，把参数转换为 string_to_sign, 然后用 HMAC-SHA256 算法和你的 secret_key 进行签名。

string_to_sign 的生成方式

上面的公式中的 string_to_sign 由五部分组成：

  string_to_sign = http_method + path + access_key + tonce + payload.to_json
  signature = OpenSSL::HMAC.hexdigest 'SHA256', secret_key, string_to_sign

var utf8 = require("utf8");
var crypto = require("crypto");
signature = crypto.createHmac('sha256', secret_key).update(utf8.encode(payload_str)).digest('hex');

那么最终用于签名的原字符串，就是把这五个部分链接起来皆可（注意顺序不可颠倒）。

授权

知人为第三方服务进行标准 Oauth2 协议授权，允许操作用户数据，通过 API 请求用户数据前，需要实现进行授权，并取得授权 token。

对应的每个第三方服务，都有唯一的 app_id ，app_secret与 callback_url。 对应的每个第三方服务的每个用户，都有唯一的response_code， access_token。

错误码

正常API返回的 HTTP Status Code 为 2xx 或 3xx。如果遇到错误，HTTP Status Code 为 4xx 或 5xx, 同时返回报文内容会包含具体错误信息，包括错误代码和错误消息。

API 错误代码列表

更新日志

2016-09-09
创建文档

2016-12-29
新增员工提醒、出勤员工、Moka 候选人 API

2017-01-08
新增获取子公司、子公司部门、子公司员工信息的 API

2017-01-17
新增绑定、解绑 Moka 公司以及查询 bind_code 有效性的 API

2017-03-18
新增出勤打卡 API

2017-06-06
Department 对象去掉 sub_company 字段，移除如下接口：
GET /api/v2/sub_companies/:sub_company_uuid/departments
GET /api/v2/sub_companies/:sub_company_uuid/departments/:uuid

2017-06-20
Employee 对象中新增 job_title 字段

2017-07-07
Employee 对象中新增 leader_uuid, virtual_leader_uuid 字段，Department 对象中新增 charger_uuid 字段，新增根据 uuid 查找员工信息

公司

Company

分公司

Sub Company

部门

Department

员工

Employee

员工类型说明 (category)

Parameters

fulltime

全职

part_time

兼职

intern

实习生

contractor

劳务派遣

员工状态说明 (status)

Parameters

waiting

待入职

probation

试用期

regular

在职

dimission

离职

internship

实习期

候选人

Candidate

排班

Arrangement

打卡

Attendance Checking

Timeline

Timeline

审批对象

Approval

获取所有分公司

GET /api/v2/sub_companies

HTTP Parameters

Response

JSON 格式的 分公司对象 数组

获取单个分公司

GET /api/v2/sub_companies/:sub_company_uuid

Parameters

sub_company_uuid

分公司 uuid

HTTP Parameters

Response

JSON 格式的 分公司对象

查询分公司员工

GET /api/v2/sub_companies/:sub_company_uuid/employees

Parameters

sub_company_uuid

分公司 uuid

HTTP Parameters

Response

JSON 格式的 员工对象 数组

单个员工查询

GET /api/v2/sub_companies/:sub_company_uuid/employees/:uuid

Parameters

sub_company_uuid

分公司 uuid

uuid

员工 uuid

HTTP Parameters

Response

JSON 格式的 员工对象 数组

获取所有部门

GET /api/v2/departments

HTTP Parameters

Response

JSON 格式的 部门对象 数组

获取单个部门

GET /api/v2/departments/:uuid

Parameters

uuid

部门 uuid

HTTP Parameters

Response

JSON 格式的 部门对象

查询部门员工

GET /api/v2/departments/:uuid/employees

HTTP Parameters

Payload Schema

Pagination Schema

Response

全部获取时

JSON 格式的 员工对象 数组

分页获取时

获取所有员工

GET /api/v2/employees

HTTP Parameters

Payload Schema

Pagination Schema

Response

全部获取时

JSON 格式的 员工对象 数组

分页获取时

按工号查询员工

GET /api/v2/employees/:empno

Parameters

empno

员工工号

HTTP Parameters

Payload Schema

Response

JSON 格式的 员工对象

按手机号查询员工

GET /api/v2/employees/:mobile

Parameters

mobile

手机号码

HTTP Parameters

Payload Schema

Response

JSON 格式的 员工对象

按uuid查询员工

GET /api/v2/employees/:uuid

Parameters

uuid

员工 uuid

HTTP Parameters

Payload Schema

Response

JSON 格式的 员工对象

检查员工当天是否出勤

GET /api/v2/employees/:uuid/check_attendance

HTTP Parameters

Payload Schema

Response

员工对象

导入员工打卡记录

POST /api/v2/attendance_punches

HTTP Parameters

Payload Schema

attendances: [
  { "empno": "NORMAL-1", "punched_at": "2017-02-03 08:00" },
  { "empno": "1100", "punched_at": "2017-02-03 08:00" },
  { "empno": "1100", "punched_at": "2017-02-03 08:00" }
]

Response

包含传递过来的每一条打卡数据的状态，格式为：

[
  { code: "0k", empno: "007" },
  { code: "error", empno: "008", error_message: "employee not found" }
]

查询员工排班

GET /api/v2/arrangement_employees

HTTP Parameters

Payload Schema

Response

排班对象 数组

查询请假和公出

GET /api/v2/employees/:guid/timelines

HTTP Parameters

Payload Schema

Response

Timeline 对象 数组

获取员工打卡记录

GET /api/v2/employees/:guid/attendance_checkings

HTTP Parameters

Payload Schema

Response

JSON 格式的 打卡对象 数组

薪酬科目上传

POST /api/v2/salary/subject_values

HTTP Parameters

{
  "empno": "001",              # 员工工号
  "subject_name": "绩效工资",   # 薪酬科目名称
  "month": "2017-09",          # 计薪月份，格式: "yyyy-mm"
  "value": 1024.12             # 金额，精确到小数点后两位
}

同一员工薪酬如果上传多次（相同月份），则以最后一次数据为准

Response

  { "code": "返回码", "text": "error message" } # 0 表示成功

更新公司令牌

PATCH /api/v2/company_tokens/:guid

HTTP Parameters

Payload Schema

提醒员工接见访客

POST /api/v2/employees/:guid/notify

HTTP Parameters

Payload Schema

Response

员工对象

获取审批列表

GET /api/v2/approvals

HTTP Parameters

{
  "start_date": "2018-02-01",              # 发起审批开始日期
  "end_date": "2018-03-01",                # 发起审批截止日期
  "category": "leave"                      # 审批类型，不传该参数代表获取所有审批类型
  "status": "waiting"                      # 审批状态，不传该参数代表获取所有审批状态
}

审批类型参数列表

审批状态参数列表

Response

JSON 格式的 审批对象 数组

按审批单号查询审批

GET /api/v2/approvals/:number_series

Parameters

number_series

审批单号

HTTP Parameters

Response

JSON 格式的 审批对象