使用myhrtoolkit API-技术文档

本指南涵盖了myhrtoolkit HR系统的应用程序程序员接口(API)。与您的内部或第三方软件结合使用时,我们的API将使您能够自动访问myhrtoolkit帐户并从中提取数据。

对于有兴趣构建自己的应用程序的用户,通过myhrtoolkit API进行的集成将增加附加值,例如启用定制报告或与其他业务应用程序集成。

有关API的一般介绍,请参见 CodeNewbie API简介.

我们正在添加其他端点和写入功能。它与我们对每个功能区域的重构同时进行,而不是单一的“大爆炸”方法。这样,它将逐步推出,并逐个模块提供端点。身份验证模块正在开发中。
 
尽管我们不一定能加快部署速度,但我们仍然对客户希望使用API​​的方式感兴趣。

本文档旨在使开发人员能够将myhrtoolkit API用于自己的应用程序。除身份验证以外的所有请求均为GET。

有关如何注册以获得使用myhrtoolkit API的访问权限以及如何创建和存储身份验证密钥的详细信息,请参见此。 介绍性文件.

验证中

我们使用oAuth 2.0标准进行身份验证。任何身份验证周期的第一步都是生成供API使用的访问令牌。此密钥有效期为5分钟。

POST //api.sungsim.cn/oauth/access_token

必填参数:

grant_type 必须将其设置为密码。
client_id 这是您的客户编号
client_secret 这是您的身份验证密钥
username 这是您用于API访问的控制器的用户名
password 这是控制器的密码

所有参数 一定是 x-www-form-urlencoded.

 

PHP cUrl示例

$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => "//api.sungsim.cn/oauth/access_token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=password&client_id=YOUR_CLIENT_ID
         &client_secret=YOUR_CLIENT_SECRET&username=YOUR_CONTROLLER_USERNAME
         &password=YOUR_CONTROLLER_PASSWORD", 
    CURLOPT_HTTPHEADER => array(
      "cache-control: no-cache",
      "content-type: application/x-www-form-urlencoded"
      ),
    ));
 
    $response = curl_exec($curl);

成功请求后,响应将采用以下JSON格式。

{
    "access_token": "RNShyENb3HCrPds3rAS2OJibe76ISfqM2qi729rr",
    "token_type": "Bearer",
    "expires_in": 3600
}

如果请求失败,则响应如下:

{
    "error": "invalid_client",
    "error_description": "Client authentication failed."
}

error和error_description值将反映失败的原因,例如 无效的client_id 要么 client_secret 在上面的示例中,或 unsupported_grant_type.
API用户有权访问所有客户端数据。实际上,他们作为控制者访问您的信息。

发出请求

使用有效的访问令牌,现在可以向API发出请求。
每个请求必须在Authorization标头中包含提供的访问令牌。
没有授权令牌或授权令牌无效的请求将作为响应收到400状态代码,类似于:

{
    "error": "invalid_request",
    "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, 要么 is otherwise malformed. Check the \"access token\" parameter."
}

可以在URL查询字符串中发送其他参数。这些将在下面的相关章节中进行描述。

PHP cUrl示例

$curl = curl_init();
    curl_setopt_array($curl, array(
    CURLOPT_URL => "//api.sungsim.cn/public/users/1",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
    "authorization: Bearer 7H4FVwZ1w3qDuqUbjINA3MeO9DHKcldWnzbu72Fz"
    ),
));

$response = curl_exec($curl);

收到回应

所有响应均为JSON格式,带有标记为“数据”的根对象,状态码为200。
对GET / public / users / 123请求的响应示例

{
    "data": {
        "id": 123,
        "created": "2006-01-19 16:23:16",
        "contact_id": "225",
        "department": "Sales",
        "location": "New York",
        "firstname": "Peter",
        "surname": "Green",
        "gender": "Male",
        "email": "me@work.com",
        "telephone": "+441142563435",
        "links": [
            {
                "rel": "self",
                "uri": "/public/users/123"
            }
        ]
    }
}
日期和时间格式

所有日期和时间均采用YYYY-MM-DD HH:MM:SS的ISO格式

分页

默认情况下,对所有响应进行分页,一次返回50条记录。
当前分页的详细信息在响应的meta属性中给出,如下例所示。

"meta": {
    "pagination": {
        "total": 135,
        "count": 50,
        "per_page": 50,
        "current_page": 1,
        "total_pages": 3,
        "links": {
            "next": "//api.sungsim.cn/public/departments/123/users/?page=2"
        }
    }
}

The URL required to continue to the next page is given in the links:next attribute.

API端点:用户
GET /public/users 返回您组织的所有用户的列表。
GET /public/users/{id} 返回所选用户的摘要信息。
GET /public/users/{id}/holidays 返回当前日历年中所选用户的所有假期的列表。

允许的参数:
年= YYYY
您希望显示假期的年份。
GET /public/users/{id}/holidaydashboard 返回当前假期年度所选用户的假期信息的摘要。
API端点:假期
GET /public/holidays 返回您组织的假期列表。

允许的参数:
年= YYYY
您希望显示假期的年份。
GET /public/holidays/{id} 返回所请求假日ID的摘要详细信息。
API端点:位置
GET /public/locations 返回组织的位置列表。
GET /public/locations/{id} 返回所请求位置的摘要详细信息。
GET /public/locations/{id}/users 返回所请求位置的用户列表。
GET /public/locations/{id}/holidays 返回所请求位置的用户的假日列表。
API端点:部门
GET /public/departments 返回您组织的部门列表。
GET /public/departments/{id} 返回所请求部门的摘要详细信息。
GET /public/departments/{id}/users 返回所请求部门中的用户列表。
GET /public/departments/{id}/holidays 返回所请求部门中用户的假日列表。
API端点:薪水
GET /public/salaries 返回组织中所有用户的薪水信息列表。
GET /public/salaries/user/{id} 返回所请求用户的薪水信息。
GET /public/departments/{id}/salaries 返回所请求部门的所有用户的当前薪水信息列表。
API端点:好处
GET /public/benefits 返回组织的有效福利清单。
GET /public/benefits/{id} 返回单个福利的详细信息。
GET /public/benefits/{id}/user 返回当前分配给一项权益的活动用户的列表。
GET /public/users/{id}/benefits 返回指定用户的福利列表。

对于每种福利,我们将返回以下信息:

 {
    "data": {
        "id": 123,
        "contact_id": 456,
        "title": "Company Lottery",
        "notes": "Text notes go here",
        "date_created": "2017-03-16",
        "created_by_user_id": 1234,
        "links": [
            {
                "rel": "self",
                "uri": "/public/benefits/123"
            }
        ]
    }
}