开始开发¶

调用方式¶

当你在调用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": "",
    "app_id": "",
    "app_secret": ""
}

• 参数说明

参数	是否必须	说明
corp_id	是	账号信息
app_id	是	应用凭证
app_secret	是	应用凭证密钥

• 权限说明

完成开放平台接入并创建应用后，可获得app_id和app_secret。

• 返回结果

{
   "errcode": 0,
   "errmsg": "",
   "data": {
       "access_token": "",
       "expires_in": 3600,
   }
}

参数	说明
access_token	获取到的凭证。长度为64字节
expires_in	凭证的有效时间（秒）

• 出错结果示例

{
    "errmsg":"invalid credential",
    "errcode": 401
}

注意：自 2025年3月18日 起，我们对开放平台进行了改进，支持创建多个应用。对于历史用户，原有获取ACCESS_TOKEN的方式仍然有效，如需重置corp_secret，则需按照最新方式调用。

如果您需要创建更多应用或者调整权限，请前往开发平台管理界面，按照新的方式操作。

使用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": "",
    "app_id": "",
    "app_secret": "",
    "force": 0
}

• 参数说明

参数	是否必须	说明
force	否	是否强制刷新token，1-是，0-不是。强制刷新token会导致旧token失效，请谨慎使用
corp_id	是	账号信息
app_id	是	应用凭证
app_secret	是	应用凭证密钥

• 权限说明

完成开放平台接入并创建应用后，可获得app_id和app_secret。
如果是第三方服务商使用，则需要客户先申请获得corp_id、app_id和app_secret，然后服务商向客户索要corp_id、app_id和app_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接口, 其余接口的请求包结构体与返回结果都会用app_secret作为key通过rc4算法加密, 同时返回结果头部"Content-Type: application/rc4+json"

解密示例:

• C#
• Java
• PHP
• Python