调用 API

基本要求

• 完成创建应用、申请权限、获取访问凭证、设置 IP 白名单之后，才能调用服务端 API。
• 调用 API 时，需要将访问凭证放入请求 Header 中（Authorization:Bearer <access token>）。
• 调用服务端 API 时，需要使用 HTTPS 协议、UTF-8 编码。

调用示例

向企业内员工发消息

要完成向企业内员工发消息的操作，需要调用发送消息接口，从接口文档中，可以看出，调用该接口前，需要获取 tenant_access_token。

1. 在获取访问凭证中，详细介绍了自建应用如何获取 tenant_access_token。

   获取凭证的请求示例如下：

   注意： 请将 app_id 和 app_secret 替换为实际值。

curl -X POST 'https://hi-open.zhipin.com/open-apis/auth/tenant_access_token/internal' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{"app_id":"<app_id>","app_secret":"<app_secret>"}'

2. 根据文档内的请求参数描述，调用发送消息接口。

   • 你可以发送 curl 请求，验证 API 调用结果。

     • 该 API 需要使用 POST 方式发起。

       

     • receive_id_type 作为查询参数。

     • content 、msg_type 和 receive_id 作为请求的 Body 内容。

     • 请求所需的 tenant_access_token 和 Content-Type 放在 Header 中。

     示例如下。套用如下示例时，请将参数示例值替换为实际值。

curl -X POST 'https://hi-open.zhipin.com/open-apis/im/v2/messages?receive_id_type=user_id' \
-H 'Authorization:Bearer <tenant_access_token>' \
-H 'content-type:application/json; charset=utf-8' \
-d '{      	
        "content": {              	
            "text": "Hello World"      	
        },      	
        "msg_type": "text",     	
        "receive_id": "<user_id>"  
    }'

查询用户信息

如果要查询用户信息，需要调用获取单个用户信息接口。从接口文档中，可以看出，调用该接口前，需要获取 tenant_access_token 或者 user_access_token，请根据需要获取的用户信息范围，选择合适的访问凭证。在获取访问凭证中，详细介绍了自建应用如何获取 tenant_access_token 或者 user_access_token。

• 你也可以发送 curl 请求，验证 API 调用结果。

  从接口文档中可以看出，user_id 是该接口的路径参数，例如我们查询一个 user_id 为 10001 的用户信息，示例如下：

curl -X GET 'https://hi-open.zhipin.com/open-apis/contact/v2/users/10001?user_id_type=user_id' \
-H 'Authorization: Bearer <tenant_access_token>' \
-H 'Content-Type: application/json; charset=utf-8'

响应结果

绝大多数 API 的响应体结构包括 code、msg、data 三个部分：

• code ****为错误码。如果是成功响应，code 取值为 0。
• msg ****为错误信息。如果是成功响应，msg 取值为 "success"。
• data ****为 API 的调用结果。data 在一些操作类 API 的返回中可能不存在。
• traceId ****为调用 API 的唯一标识。traceId 取值为字符串。

说明：

• 请不要依据 msg 来判定一个请求是否失败。
• 接收到失败响应后，用户可以先查看一下通用错误码说明，排查问题。如果依然不能解决问题，可以向Bosshi开放平台反馈，提供接口响应中返回的 traceId，以便我们协助定位问题。

成功响应示例：

{    
    "code": 0,
    "msg": "success",
    "traceId": "_Ao59UOIBLPCeAAu",    
    "data": {      
      // 响应的具体数据内容    
    }  
} 

失败响应示例：

{    
    "code": 40004,
    "traceId": "_Bo59UOIBLPCeAAu",    
    "msg": "no dept authority error"  
}