开始开发¶
调用方式¶
当你在调用2号人事部开放平台接口时, 需使用HTTPS协议、Json数据格式、UTF8编码, 访问域名为https://openapi.2haohr.com、数据包可选加密。
基础频率¶
- 每企业调用单个api不可超过500次/分,15000次/小时
- 企业每ip调用接口不可超过10000次/分,300000次/小时
获取ACCESS_TOKEN¶
HTTPS请求方式: POST
请求地址: https://openapi.2haohr.com/api/home/get_token/
请求包结构体为:
{
"corp_id": "",
"corp_secret": ""
}
- 参数说明
参数 | 是否必须 | 说明 |
---|---|---|
corp_id | 是 | 企业Id |
corp_secret | 是 | 企业凭证密钥 |
- 权限说明
必须先完成开放平台接入后,申请获得corp_id和corp_secret。
- 返回结果
{
"errcode": 0,
"errmsg": "",
"data": {
"access_token": "",
"expires_in": 3600,
}
}
参数 | 说明 |
---|---|
access_token | 获取到的凭证。长度为64字节 |
expires_in | 凭证的有效时间(秒) |
- 出错结果示例
{
"errmsg":"invalid credential",
"errcode": 401
}
使用ACCESS_TOKEN¶
在api的接口文档的权限说明中, 如果需要鉴权, 则需要在请求header里带上
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 鉴权ACCESS_TOKEN |
ACCESS_TOKEN是2号人事部开放平台的全局唯一接口调用凭据,调用2号人事部开放平台各业务接口时都需使用ACCESS_TOKEN。
接入2号人事部开放平台的开发者需要对ACCESS_TOKEN进行妥善保存,且ACCESS_TOKEN的有效期目前为2周,需要定期刷新,重复获取将导致上次获取的ACCESS_TOKEN失效。
ACCESS_TOKEN失效错误返回结果示例如下:
# HTTP-HEADERS status 403
{
"message": "Invalid token"
}
ACCESS_TOKEN的安全使用特别说明:
- 建议接入2号人事部开放平台的开发者统一使用中控服务获取和刷新ACCESS_TOKEN,业务逻辑服务使用的ACCESS_TOKEN均来自于该中控服务,不应该各自去创建、或刷新,否则容易造成冲突,导致ACCESS_TOKEN被覆盖而影响业务流程
- ACCESS_TOKEN的有效期通过get_token返回的expires_in来传达。中控服务器需要根据这个有效时间提前去刷新新ACCESS_TOKEN,开发者自主维护ACCESS_TOKEN确保业务稳定有效
- ACCESS_TOKEN的有效时间可能会在未来有调整,所以中控服务器不仅需要内部定时主动刷新,还需要提供被动刷新ACCESS_TOKEN的接口,这样便于业务服务在API调用获知ACCESS_TOKEN已超时的情况下,可以触发ACCESS_TOKEN的刷新流程
获取企业微信SUITE TOKEN¶
HTTPS请求方式: POST
请求地址: https://openapi.2haohr.com/api/home/get_wework_suitetoken/
请求包结构体为:
{
"corp_id": "",
"corp_secret": "",
"force": 0
}
- 参数说明
参数 | 是否必须 | 说明 |
---|---|---|
force | 否 | 是否强制刷新token,1-是,0-不是。强制刷新token会导致旧token失效,请谨慎使用 |
corp_id | 是 | 企业Id |
corp_secret | 是 | 企业凭证密钥 |
- 权限说明
必须先完成开放平台接入后,申请获得corp_id和corp_secret。
如果是第三方服务商使用,则需要客户先申请获得corp_id和corp_secret,然后服务商向客户索要corp_id和corp_secret。
- 接口说明
该接口用于获取企业微信的suite token,
目前仅支持(且默认)获取企微通讯录助手应用的token。
- token说明
该token为共享企业微信通讯录同步助手token,只适用于获取该token后调用企业微信平台接口,而非使用这个token来调用2号开放平台的接口。
在使用该token之前,请配合提供对应服务端的出口IP地址,用于配置企业微信的可信IP。
- 返回结果
{
"errcode": 0,
"errmsg": "",
"data": {
"access_token": "",
"expires_in": 3600
}
}
参数 | 说明 |
---|---|
access_token | 获取到的凭证 |
expires_in | 凭证的有效时间(秒) |
- 出错结果示例
{
"errmsg":"企业未安装该应用",
"errcode": 40004
}
数据包加密¶
如果您在申请接入时提交的资料要求加密, 除了获取ACCESS_TOKEN接口, 其余接口的请求包结构体与返回结果都会用corp_secret
作为key通过rc4算法加密, 同时返回结果头部"Content-Type: application/rc4+json"
解密示例: