飞书开放平台 Server API 文档

主题

调用 API ​

为了让开发者可以便捷地调用 API，飞书开放平台提供了 Java SDK、Go SDK、Python SDK 和 Node SDK。有关 SDK 的详细介绍，可以参考服务端 SDK。本文介绍基本的 API 调用方法。

前提条件 ​

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

调用示例 ​

向企业内员工发消息 ​

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

  1. 参考 获取访问凭证 获取 tenant_access_token。

    获取凭证的请求示例如下，你需要将 app_id 和 app_secret 替换为实际值。

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

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

    • 方式一：在调试台发起 API 调用

      image.png

    • 方式二：本地发送 curl 请求

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

      image.png

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

      bash
      curl -X POST 'https://open.feishu.cn/open-apis/im/v1/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>"
}'
      • receive_id_type 作为查询参数。
      • content 、msg_type 和 receive_id 作为请求的 Body 内容。
      • 请求所需的 tenant_access_token 和 Content-Type 放在 Header 中。

查询用户信息 ​

你可以调用获取单个用户信息接口查询用户信息。从接口文档中可以确定，调用该接口前，需要获取 tenant_access_token 或 user_access_token，请根据需要获取的用户信息范围，选择合适的访问凭证。

  1. 参考 获取访问凭证 获取 tenant_access_token 或 user_access_token。

  2. 根据文档内的请求参数描述，调用获取单个用户信息接口。

    • 方式一：在调试台发起 API 调用

    • 方式二：本地发送 curl 请求

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

      bash
      curl -X GET 'https://open.feishu.cn/open-apis/contact/v3/users/ou_c99c5f35d542efc7ee492afe11af19ef?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 ：错误信息。
  • data：API 的调用结果。data 在一些操作类 API 的返回中可能不存在。

Note

  • 请不要依据 msg 来判定一个请求是否失败。
  • 接收到失败响应后，你可以先查看 通用错误码说明，排查问题。如果依然不能解决问题，可以向飞书开放平台反馈响应头中的 x-tt-logid 值，以便我们协助定位问题。

成功响应示例：

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

失败响应示例：

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

错误响应说明 ​

飞书开放平台 OpenAPI 错误信息模块包含 HTTP 状态码、业务状态码（code）、错误信息（msg）、错误排查信息（error）四个大类。

Warning 由于在接口迭代的过程中，错误信息（msg）可能会随时发生变化，因此开发者需要避免在代码逻辑里依赖 msg，建议根据返回的业务状态码（code）判断一个请求是否失败。

错误响应结构如下所示：

json
HTTP / 1.1 400 Bad Request // HTTP 状态码
{
    "code": 44004,
    // 业务状态码
    "msg": "{error msg}, {help}, {url}.",
    // 错误信息
    "error": {
        "message": "Refer to the documentation to fix the error: https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid",
        "field_violations": [
            {
                "field": "para_a",
                "value": "testvalue_a",
                "description": "test description_a"
            }
        ],
        "permission_violations": [
            {
                "scope": "lark.im.xxx",
                "url": "https://open.feishu.cn/apps/cli_xxxx/auth"
            }
        ],
        "helps": [
            {
                "url": "https://open.feishu.cn/app/cli_a61e4f821889d00c/auth?q=event:ip_list&op_from=openapi",
                "description": "Learn more about scopes and how to add them: [event:ip_list]"
            }
        ],
        "logid": "xxx",
        "troubleshooter": "排查建议查看（Troubleshooting suggestions）：https://open.feishu.cn/search?from=openapi&log_id=XXXX&code=XXX&method_id=XXX"
    }
}
错误信息模块描述
HTTP 状态码用于进行错误分类，如客户端错误（4XX）、服务端错误（5XX）。
业务状态码 (code)代表具体的错误场景，如参数错误、鉴权错误。业务失败情况下，返回非 0 业务状态码，且 HTTP 状态码为 400 或 500 系列。
错误信息 (msg)错误码 code 关联的具体错误描述。msg 可能会优化和调整，因此不要依赖 msg 进行代码判断，建议依赖 code 进行请求失败的代码判断。
错误排查信息 (error)说明具体是哪个部分出现了问题，帮助开发者定位错误的原因，并提供建议的解决方案。
  └ message提供当前错误场景的更多帮助信息，如错误参数内容。
  └ troubleshooter该字段的值是一个链接，可以直接复制后用浏览器打开，页面中会给出错误原因分析和对应的解决方案。
note
如果你是在独立的 API 调试台或 API 文档内嵌的调试台中进行调试调用，可以直接在下方获取智能助手的详细排查建议。

logid API 调用日志 ID，可以通过在开放平台官网上搜索 logid 字段，获取详细的错误原因和排查建议。

你也可以登录开发者后台并进入调用 API 的应用的详情页，在 日志检索 > 服务端日志检索 功能页过滤出对应的 API 调用日志数据。

field_violations 代表参数错误，当请求不满足参数数据校验规则时，返回的错误信息会包含该参数。例如，某 int 类型请求参数要求传值在 1~10 之间，实际请求时传入了 11 则会报错并返回 field_violations。你的服务可依赖该参数进行代码处理。field_violation 为数组，数组内结构为 Object。结构示例如下：

json
{
    "field_violations": [
        {
            "field": "para_a",
            "value": "testvalue_a",
            "description": "test description_a"
        }
    ]
}

field 具体的错误参数

value 错误参数的取值

description 字段错误的描述

permission_violations 代表权限错误，请求时如果应用开通的权限不满足 API 需要会报错并返回该参数。你的服务可依赖该参数进行代码处理。permission_violation 为数组，数组内结构为 Object。结构示例如下：

json
{
    "permission_violations": [
        {
            "scope": "lark.im.xxx",
            "url": "https://open.feishu.cn/apps/cli_xxxx/auth"
        }
    ]
}

scope 需要开通的权限。

url 对应的添加权限的地址。可以点击后直接前往开发者后台权限页面进行申请开通。

helps 权限不足时返回该参数，你可以访问 URL 快速跳转到缺失权限的应用 API 权限页面开通权限。结构示例如下：

json
{
    "helps": [
        {
            "url": "https://open.feishu.cn/app/cli_a61e4f1234xxx/auth?q=event:ip_list&op_from=openapi",
            "description": "Learn more about scopes and how to add them: [event:ip_list]"
        }
    ]
}

url 对应的添加权限的地址。可以点击后直接前往开发者后台权限页面进行申请开通。

description 提供缺失的权限信息。

相关教程 ​

你也可参考以下教程快速体验如何调用服务端 API：

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有