API调用

流程

URL说明

对外使用统一的域名openapi.hiar.com，不同的能力通过在URI上增加一层目录来区分

如:

https://openapi.hiar.com/hris       代表hris开放能力
https://openapi.hiar.com/leliaRTC   代表leliaRTC能力

在流量网关处，会对请求进行转发以及URL重写

会话信息

认证通过后，会通过Header传递会话信息，KEY为x-openapi-session-data，内容格式为JSON字符串，如下:

{"corp_id": 1}

调用方式

Content-Type 为 application/json

返回的HTTP状态码均为200

认证

认证方式

需要在http.header传递以下信息

// 由企业平台上查看
X-HIAR-OPENAPI-APPID: hiar01231230123
// 随机生成uuid
X-HIAR-OPENAPI-NONCE: 5a63aa78-f6bc-11ec-b939-0242ac120002
// 符合RF3339标准的时间
X-HIAR-OPENAPI-DATE: 2022-06-27T16:34:04+08:00
// 通过特定的加密规则生成签名
X-HIAR-OPENAPI-SIGNATURE: X1RAmXcABtwvKnaIYEY5a1O65Nm0y6gfVHbIBz7t668=

签名生成规则

签名的计算公式为signature=HMAC-SHA256-HEX(secret, signing_string)。
需要两个参数：secret和signing_string

secret由平台上创建应用后生成

signing_string的计算公式为signing_string = HTTP METHOD + \n + PATH + \n + canonical_query_string + \n + app_id + \n + date + \n + nonce + \n

以上参数说明:

HTTP Method：指 HTTP 协议中定义的 GET、PUT、POST 等请求方法，小写格式。

PATH：即http uri部分，必须以 “/” 开头，不包含query

canonical_query_string：对 URL 中的 query（query 即 URL 中 ? 后面的 key1=valve1&key2=valve2 字符串）进行编码后的结果。

按key从小到大进行排序，然后按key=value格式进行拼接，多个key用&连接，如果key存在重复key值，按对应value升序，在拼接。如: name=paul&age=19&age=20

没有传空字符串

app_id 平台生成的应用ID

date 符合RF3339的时间格式

nonce 随机数

signing_string拼接后例子:

"get
/account/v1/user
page=1&limit=10
hiar1d98ncv515f5e1
2022-07-05T17:46:33+08:00
5a71e2ec-fc47-11ec-81db-acde48001122
"

最后一个请求头也需要 + \n。

按指定格式拼接好，使用sha256算法进行加密，加密后在做一次base64编码

signature结果验证：

bash
# signature生成伪代码
signature = base64(sha256(signing_string, secret))

# secret: IkcyCWpRxjCztzvOjHdLKKfgTpzmCqQ1
# 按上面signing_string拼接例子和secret生成的signature如下:
+TfnNKz8XTvZJNpFSrnlLk+3m1swS+jhRuKxemo7YLQ=

成功返回示例：

{
    "code": 0,
    "reason": "SUCCESS",
    "message": "操作成功",
    "data": {
        ...
    }
}

失败返回示例：

{
    "code": 1001,
    "reason": "INVALID_PARAM",
    "message": "参数错误"
}

API接入说明

API调用#

流程#

URL说明#

会话信息#

调用方式#

认证#

认证方式#

签名生成规则#

返回#