Feishu Open Platform

https://open.larkoffice.com/document/
Admin
Feishu Open Platform provides developers with APIs, SDKs, and tools to build custom applications,...
Tokens:1,138,692
Snippets:7,637
Trust Score:7.2
Update:3 months ago
Show doc for...
Tokens:
Raw
### Set up HTTP Server for Events (Go)

Source: https://open.larkoffice.com/document/corehr-v1/organization-management/company/events/deleted

Create an HTTP server to listen for incoming webhook events. Use `httpserverext.NewEventHandlerFunc` to handle events and specify log level.

```go
// 创建路由处理器 Create route handler
	http.HandleFunc("/webhook/event", httpserverext.NewEventHandlerFunc(handler, larkevent.WithLogLevel(larkcore.LogLevelDebug)))
```

```go
err := http.ListenAndServe(":7777", nil)

	if err != nil {
		panic(err)
	}
```

--------------------------------

### Get Custom Section List Example

Source: https://open.larkoffice.com/document/task-v2/section/list

This JSON response shows a successful retrieval of custom sections, including their GUID, name, default status, and pagination information.

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "guid": "e6e37dcc-f75a-5936-f589-12fb4b5c80c2",
                "name": "审核过的任务",
                "is_default": true
            }
        ],
        "page_token": "aWQ9NzEwMjMzMjMxMDE=",
        "has_more": true
    }
}
```

--------------------------------

### Batch Get Employee Job Data Request Example

Source: https://open.larkoffice.com/document/corehr-v1/employee/job_data/batch_get

This example demonstrates the structure of a request body for batch querying employee job data. It includes employment IDs and optional parameters for filtering by version, effective dates, primary job data, and assignment start reasons.

```json
{
    "employment_ids": [
        "7140964208476371111"
    ],
    "get_all_version": false,
    "effective_date_start": "2020-01-01",
    "effective_date_end": "2020-01-01",
    "data_date": "2020-01-01",
    "primary_job_data": true,
    "assignment_start_reasons": [
        "onboarding"
    ]
}
```

--------------------------------

### Example Select Options Configuration

Source: https://open.larkoffice.com/document/feishu-cards/feishu-card-cardkit/configure-card-variables

Provides a concrete example of how to configure options for a select component, including standard and custom icons, and internationalized text.

```json
[
  {
    "text": "选项 1",
    "value": "1",
    "selected": true,
    "icon": {
      "tag": "standard_icon",
      "token": "chat-forbidden_outlined"
    },
    "i18n_text": {
      "zh_cn": "选项 1"
    }
  },
  {
    "text": "选项 2",
    "value": "2",
    "icon": {
      "tag": "custom_icon",
      "img_key": "img_v3_02er_196d133d-aa22-4021-9b79-c11105223e4j"
    },
    "i18n_text": {
      "zh_cn": "选项 2"
    }
  },
  {
    "text": "选项 3",
    "value": "3",
    "i18n_text": {
      "zh_cn": "选项 3"
    }
  }
]
```

--------------------------------

### Get Job Type List API Request Example

Source: https://open.larkoffice.com/document/hire-v1/recruitment-related-configuration/job/list-4

This is an example of a GET request to the job types endpoint. Ensure you include the 'Authorization' header with your tenant access token.

```http
GET https://open.feishu.cn/open-apis/hire/v1/job_types
Content-Type: application/json
Authorization: Bearer t-7f1bcd13fc57d46bac21793a18e560
```

--------------------------------

### Flask Server Setup and Initialization

Source: https://open.larkoffice.com/document/quickly-create-a-login-free-web-app/introduction-to-sample-code

Initializes a Flask web application, sets up logging, loads environment variables, and configures authentication using provided credentials.

```python
  #!/usr/bin/env python
  # -*- coding: UTF-8 -*-
  import os
  import logging

from auth import Auth
from dotenv import load_dotenv, find_dotenv
from flask import Flask, render_template, session, jsonify, request

# 日志格式设置
  LOG_FORMAT = "%(asctime)s - %(message)s"
  DATE_FORMAT = "%m/%d/%Y %H:%M:%S"
  logging.basicConfig(level=logging.DEBUG, format=LOG_FORMAT, datefmt=DATE_FORMAT)

# const
  # 在session中存储用户信息 user info 所需要的对应 session key
  USER_INFO_KEY = "UserInfo"
  # secret_key 是使用 flask session 所必须有的
  SECRET_KEY = "ThisIsSecretKey"

# 从 .env 文件加载环境变量参数
  load_dotenv(find_dotenv())

# 初始化 flask 网页应用
  app = Flask(__name__, static_url_path="/public", static_folder="./public")
  app.secret_key = SECRET_KEY
  app.debug = True

# 获取环境变量值
  APP_ID = os.getenv("APP_ID")
  APP_SECRET = os.getenv("APP_SECRET")
  FEISHU_HOST = os.getenv("FEISHU_HOST")

# 用获取的环境变量初始化免登流程类Auth
  auth = Auth(FEISHU_HOST, APP_ID, APP_SECRET)

# 业务逻辑类
  class Biz(object):
      @staticmethod
      def home_handler():
          # 主页加载流程
          return Biz._show_user_info()

@staticmethod
      def login_handler():
          # 需要走免登流程
          return render_template("index.html", user_info={"name": "unknown"}, login_info="needLogin")

@staticmethod
      def login_failed_handler(err_info):
          # 出错后的页面加载流程
          return Biz._show_err_info(err_info)

```

--------------------------------

### Create HTTP Server and Handle Events (Go)

Source: https://open.larkoffice.com/document/corehr-v1/basic-compensation/archive/events/changed

Create an HTTP server to handle incoming webhook events. This includes setting up the event handler and starting the server.

```go
// 创建路由处理器 Create route handler
	http.HandleFunc("/webhook/event", httpserverext.NewEventHandlerFunc(handler, larkevent.WithLogLevel(larkcore.LogLevelDebug)))

err := http.ListenAndServe(":7777", nil)

if err != nil {
		panic(err)
	}
```

--------------------------------

### Get Task List API Request Example

Source: https://open.larkoffice.com/document/task-v2/tasklist/tasks

This example demonstrates how to make a GET request to retrieve tasks from a specific task list. Ensure you have the necessary permissions and include the tasklist_guid in the URL.

```http
GET https://open.feishu.cn/open-apis/task/v2/tasklists/:tasklist_guid/tasks
Header:
Authorization: Bearer u-7f1bcd13fc57d46bac21793a18e560
Query:
page_size=50
completed=true
created_from=1675742789470
created_to=1675742789470
```

--------------------------------

### List Tasks in Tasklists API Response Example

Source: https://open.larkoffice.com/document/task-v2/task/tasklists

This is an example of a successful response from the List Tasks in Tasklists API. It shows the structure of the returned data, including the tasklist GUID and section GUID.

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "tasklists": [
            {
                "tasklist_guid": "cc371766-6584-cf50-a222-c22cd9055004",
                "section_guid": "e6e37dcc-f75a-5936-f589-12fb4b5c80c2"
            }
        ]
    }
}
```

--------------------------------

### Build Client and Establish Connection (Node.js)

Source: https://open.larkoffice.com/document/hire-v1/referral_account/events/assets_update

Initializes a Lark WSClient with application credentials and starts a persistent connection. Event listeners for specific events like 'hire.referral_account.assets_update_v1' are registered within the start options.

```javascript
const baseConfig = {
    appId: 'APP_ID',
    appSecret: 'APP_SECRET'
}
// 构建 client Build client
const wsClient = new Lark.WSClient(baseConfig);
// 建立长连接 Establish persistent connection
wsClient.start({
    // 注册事件 Register event
    eventDispatcher: new Lark.EventDispatcher({}).register({
        'hire.referral_account.assets_update_v1': async (data) => {
            console.log(data);
        }
    })
});
```

--------------------------------

### Start the Local Service

Source: https://open.larkoffice.com/document/quickly-create-a-login-free-web-app/start-the-local-service

Run the server.py script to start the local web service. A temporary domain will be generated upon successful startup.

```Shell
python server.py
```

--------------------------------

### Get Image URL Example

Source: https://open.larkoffice.com/document/client-docs/gadget/-web-app-api/open-ability/chat/getBlockActionSourceDetail

Example JSON structure for obtaining an image URL through an API.

```json
{
    "url":"https://open.feishu.cn/open-apis/im/v1/images/:image_key"
}
```

--------------------------------

### Batch Get Departments Request Body Example

Source: https://open.larkoffice.com/document/corehr-v1/organization-management/department/batch_get

This example demonstrates how to structure the request body for the batch get departments API, including specifying department IDs, fields to retrieve, and department names for filtering.

```json
{
    "department_id_list": [
        "7094136522860922111"
    ],
    "fields": [
        "version_id"
    ],
    "department_name_list": [
        "综合部"
    ]
}
```

--------------------------------

### Download and Unzip Example Code (Windows)

Source: https://open.larkoffice.com/document/quickly-create-a-login-free-web-app/start-the-local-service

Use curl to download the example code and extract it using tar. Navigate to the Python directory.

```Shell
curl https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/8841fb595ea110a900ef092f52e80fd0_VFYrhlOpLw.zip -o web_app_with_auth.zip
tar -xzvf web_app_with_auth.zip
cd web_app_with_auth/python
```

--------------------------------

### Start SSO Verification and Handle Callback

Source: https://open.larkoffice.com/document/common-capabilities/sso/mobile-app/sdk

Demonstrates how to initiate the SSO verification process and handle the success or error callbacks.

```APIDOC
## Start SSO Verification and Handle Callback

### Description

This snippet illustrates how to invoke the SSO verification process using the configured `LarkBuilder` and provides a callback interface to handle the results, including success and error scenarios.

### Method

```typescript
const callback: IGetDataCallback = {
      onSuccess: (code:CallBackData) => {
         const msg = JSON.stringify(code)
         console.info("OhDemo onSuccess", JSON.stringify(code))
      },
      onError: (code:CallBackData) => {
         const msg = JSON.stringify(code)
         console.info("OhDemo onError", msg)
      },
  }
  LarkSSO.startSSOVerify(larkBuilder, callback)
```

### Parameters

- `larkBuilder` (LarkBuilder): The configured builder object for SSO verification.
- `callback` (IGetDataCallback): An object implementing the `IGetDataCallback` interface with `onSuccess` and `onError` methods to handle the verification result.
```

--------------------------------

### Company Batch Get Response Example

Source: https://open.larkoffice.com/document/corehr-v1/organization-management/company/batch_get

This example demonstrates the structure of a successful response when retrieving multiple companies.

```APIDOC
## Response

### Success Response (200)

- **code** (integer) - 0 indicates success, non-zero indicates an error.
- **msg** (string) - A message describing the result of the operation.
- **data** (object) - Contains the list of companies.
  - **items** (array) - A list of company objects.
    - **company_id** (string) - The unique identifier for the company.
    - **hiberarchy_common** (object) - Common hierarchical information for the company.
      - **parent_id** (string) - The ID of the parent company or entity.
      - **name** (array) - An array of localized names for the company.
        - **lang** (string) - The language code (e.g., 'zh-CN').
        - **value** (string) - The translated name.
      - **type** (object) - The type of the company hierarchy node.
        - **enum_name** (string) - The enumeration name for the type.
        - **display** (array) - Localized display names for the type.
          - **lang** (string) - The language code.
          - **value** (string) - The display value.
      - **active** (boolean) - Indicates if the company hierarchy node is active.
      - **effective_time** (string) - The start date/time for the validity of this record.
      - **expiration_time** (string) - The end date/time for the validity of this record.
      - **code** (string) - A code associated with the company hierarchy node.
      - **description** (array) - Localized descriptions for the company hierarchy node.
        - **lang** (string) - The language code.
        - **value** (string) - The description.
      - **tree_order** (string) - Ordering value for tree structures.
      - **list_order** (string) - Ordering value for list views.
      - **custom_fields** (array) - A list of custom fields associated with the company.
        - **field_name** (string) - The name of the custom field.
        - **value** (string) - The value of the custom field.
    - **type** (object) - The type of the company.
      - **enum_name** (string) - The enumeration name for the company type.
      - **display** (array) - Localized display names for the company type.
        - **lang** (string) - The language code.
        - **value** (string) - The display value.
    - **industry_list** (array) - A list of industries the company belongs to.
      - **enum_name** (string) - The enumeration name for the industry.
      - **display** (array) - Localized display names for the industry.
        - **lang** (string) - The language code.
        - **value** (string) - The display value.
    - **legal_representative** (array) - Localized names of the legal representative.
      - **lang** (string) - The language code.
      - **value** (string) - The name.
    - **post_code** (string) - The postal code of the company.
    - **tax_payer_id** (string) - The tax payer identification number.
    - **confidential** (boolean) - Indicates if the company information is confidential.
    - **sub_type_list** (array) - A list of sub-types for the company.
      - **enum_name** (string) - The enumeration name for the sub-type.
      - **display** (array) - Localized display names for the sub-type.
        - **lang** (string) - The language code.
        - **value** (string) - The display value.
    - **branch_company** (boolean) - Indicates if this is a branch company.
    - **primary_manager** (array) - Localized names of the primary manager.
      - **lang** (string) - The language code.
      - **value** (string) - The name.
    - **currency** (object) - Information about the company's currency.
      - **currency_id** (string) - The unique identifier for the currency.
      - **country_region_id_list** (array) - List of country/region IDs associated with the currency.
      - **currency_name** (array) - Localized names of the currency.
        - **lang** (string) - The language code.
        - **value** (string) - The currency name.
      - **numeric_code** (integer) - The numeric code for the currency.
      - **currency_alpha_3_code** (string) - The 3-letter alpha code for the currency (e.g., 'CNY').
      - **status** (integer) - The status of the currency (e.g., 1 for active).
    - **phone** (object) - The company's phone number.
      - **area_code** (object) - The area code for the phone number.
        - **enum_name** (string) - The enumeration name for the area code type.
        - **display** (array) - Localized display names for the area code.
          - **lang** (string) - The language code.
          - **value** (string) - The display value.
      - **phone_number** (string) - The phone number.
    - **fax** (object) - The company's fax number.
      - **area_code** (object) - The area code for the fax number.
        - **enum_name** (string) - The enumeration name for the area code type.
        - **display** (array) - Localized display names for the area code.
          - **lang** (string) - The language code.
          - **value** (string) - The display value.
      - **phone_number** (string) - The fax number.
    - **registered_office_address** (array) - Localized registered office addresses.
      - **lang** (string) - The language code.
      - **value** (string) - The address.
    - **office_address** (array) - Localized office addresses.
      - **lang** (string) - The language code.
      - **value** (string) - The address.
    - **registered_office_address_info** (object) - Detailed information about the registered office address.
      - **full_address_local_script** (string) - The full address in the local script.
      - **full_address_western_script** (string) - The full address in the western script.
```

--------------------------------

### Image Component Card Example

Source: https://open.larkoffice.com/document/feishu-cards/card-components/content-components/image

A complete card example demonstrating the image component with specific configurations for preview, scaling, and size. Replace `img_key` with your actual image key.

```json
{
    "config": {},
    "card_link": {
        "url": "",
        "pc_url": "",
        "ios_url": "",
        "android_url": ""
    },
    "i18n_elements": {
        "zh_cn": [
            {
                "tag": "img",
                "img_key": "img_v2_ace8a4f2-ae13-420f-9eb3-b3530b4abcef",
                "preview": true,
                "scale_type": "crop_top",
                "size": "stretch"
            }
        ]
    },
    "i18n_header": {}
}
```

--------------------------------

### Get Installed Applications

Source: https://open.larkoffice.com/document/application-v6/admin/list

Queries the list of applications installed in an enterprise. This endpoint is designed for self-built enterprise applications.

```APIDOC
## GET /open-apis/application/v6/applications

### Description
Queries the list of applications installed in an enterprise. This endpoint can only be called by self-built enterprise applications.

### Method
GET

### Endpoint
https://open.feishu.cn/open-apis/application/v6/applications

### Parameters
#### Query Parameters
- **page_size** (int) - Optional - The number of items to return per page. Defaults to 50. Maximum value is 50.
- **page_token** (string) - Optional - The pagination marker. Use this to retrieve subsequent pages of results.
- **user_id_type** (string) - Optional - The type of user ID to return. Defaults to 'open_id'.
- **lang** (string) - Required - The language for application information. Options: 'zh_cn', 'en_us', 'ja_jp'. Defaults to the application's primary language if not provided.
- **status** (int) - Optional - Filters applications by their status. Options: 0 (Disabled), 1 (Enabled), 2 (Not Enabled).
- **payment_type** (int) - Optional - Filters applications by payment type. Options: 0 (Free), 1 (Paid).
- **owner_type** (int) - Optional - Filters applications by owner type. Options: 0 (Lark Technology), 1 (Lark Partner), 2 (Enterprise Member).

### Request Headers
- **Authorization** (string) - Required - `tenant_access_token`. Format: "Bearer `access_token`". Example: "Bearer t-7f1bcd13fc57d46bac21793a18e560"
```

--------------------------------

### Golang OAuth 2.0 User Access Token Example

Source: https://open.larkoffice.com/document/authentication-management/access-token/get-user-access-token

This Golang code demonstrates how to set up an OAuth 2.0 client to obtain a user's access token. It includes configuration for the OAuth endpoint, client ID, client secret, and redirect URL. The example uses the Gin web framework to handle the authorization and callback requests.

```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "math/rand"
    "net/http"
    "os"

    "github.com/gin-contrib/sessions"
    "github.com/gin-contrib/sessions/cookie"
    "github.com/gin-gonic/gin"
    _ "github.com/joho/godotenv/autoload"
    "golang.org/x/oauth2"
)

var oauthEndpoint = oauth2.Endpoint{
    AuthURL:  "https://accounts.feishu.cn/open-apis/authen/v1/authorize",
    TokenURL: "https://open.feishu.cn/open-apis/authen/v2/oauth/token",
}

var oauthConfig = &oauth2.Config{
    ClientID:     os.Getenv("APP_ID"),
    ClientSecret: os.Getenv("APP_SECRET"),
    RedirectURL:  "http://localhost:8080/callback", // 请先添加该重定向 URL，配置路径：开发者后台 -> 开发配置 -> 安全设置 -> 重定向 URL -> 添加
    Endpoint:     oauthEndpoint,
    Scopes:       []string{"offline_access"}, // 如果你不需要 refresh_token，请注释掉该行，否则你需要先申请 offline_access 权限方可使用，配置路径：开发者后台 -> 开发配置 -> 权限管理      
}

func main() {
    r := gin.Default()

// 使用 Cookie 存储 session
    store := cookie.NewStore([]byte("secret")) // 此处仅为示例，务必不要硬编码密钥
    r.Use(sessions.Sessions("mysession", store))

r.GET("/", indexController)
    r.GET("/login", loginController)
    r.GET("/callback", oauthCallbackController)

fmt.Println("Server running on http://localhost:8080")
    log.Fatal(r.Run(":8080"))
}

func indexController(c *gin.Context) {
    c.Header("Content-Type", "text/html; charset=utf-8")
    var username string
    session := sessions.Default(c)
    if session.Get("user") != nil {
       username = session.Get("user").(string)
    }
    html := fmt.Sprintf(`<html><head><style>body{font-family:Arial,sans-serif;background:#f4f4f4;margin:0;display:flex;justify-content:center;align-items:center;height:100vh}.container{text-align:center;background:#fff;padding:30px;border-radius:10px;box-shadow:0 0 10px rgba(0,0,0,0.1)}a{padding:10px 20px;font-size:16px;color:#fff;background:#007bff;border-radius:5px;text-decoration:none;transition:0.3s}a:hover{background:#0056b3}}</style></head><body>[返回主页](/)</body></html>`, user.Data.Name)
    c.String(http.StatusOK, html)
}

```

--------------------------------

### Delete Attachment Request Example

Source: https://open.larkoffice.com/document/task-v2/attachment/delete

This example demonstrates how to make a DELETE request to remove an attachment. Ensure you have the necessary permissions and the correct attachment GUID.

```bash
curl --location --request DELETE \
    'https://open.feishu.cn/open-apis/task/v2/attachments/:attachment_guid' \
    --header 'Authorization: Bearer u-7f1bcd13fc57d46bac21793a18e560'
```

--------------------------------

### Image Component Example

Source: https://open.larkoffice.com/document/feishu-cards/card-json-v2-components/content-components/image

This example demonstrates the basic usage of the image component with a specific image key, preview enabled, and the 'crop_center' scale type. It also sets the image size to 'stretch' and includes an alternative text description.

```JSON
{
  "schema": "2.0",
  "body": {
    "direction": "vertical",
    "padding": "12px 12px 12px 12px",
    "elements": [
      {
        "tag": "img",
        "img_key": "img_v2_9dd98485-2900-4d65-ada9-e31d1408dcfg",
        "preview": true,
        "transparent": false,
        "scale_type": "crop_center",
        "size": "stretch",
        "alt": {
          "tag": "plain_text",
          "content": "示例图片"
        },
        "corner_radius": "5%",
        "margin": "0px 0px 0px 0px",
        "element_id": "demoimg01"
      }
    ]
  }
}
```

--------------------------------

### Response Body Example for Get Agency Account

Source: https://open.larkoffice.com/document/hire-v1/get-candidates/agency/get_agency_account

This example shows a successful response from the 'get_agency_account' API. It includes pagination information, a list of recruiters, and their details.

```json
{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "has_more": true,
        "page_token": "eyJvZmZzZXQiOjEsInRpbWVzdGFtcCI6MTY0MDc2NTYzMjA4OCwiaWQiOm51bGx9",
        "items": [
            {
                "id": "6995312261554538796",
                "reason": "这个猎头很不负责",
                "create_time": "1639992265035",
                "status": 1,
                "user_info": {
                    "user_id": "7398623155442682156",
                    "name": {
                        "zh_cn": "张三",
                        "en_us": "Zhangsan"
                    },
                    "email": "27188272xxxx1.com",
                    "mobile": "1879087xxx8"
                },
                "role": 1
            }
        ]
    }
}
```

--------------------------------

### getLaunchOptionsSync()

Source: https://open.larkoffice.com/document/client-docs/gadget/-web-app-api/open-ability/feishu-launch-parameters/getlaunchoptionssync

This synchronous method retrieves the parameters used when a mini-program experiences a cold start. The callback parameters are consistent with `App.onLaunch`.

```APIDOC
## getLaunchOptionsSync()

### Description
This synchronous method retrieves the parameters used when a mini-program experiences a cold start. The callback parameters are consistent with `App.onLaunch`.

### Method
Synchronous function call

### Endpoint
N/A (Client-side SDK method)

### Parameters
This method takes no input parameters.

### Output
Returns an object containing launch options:
- **data** (object) - Contains the launch options.
  - **path** (string) - The launch page path of the mini-program.
  - **query** (object) - The launch parameters of the mini-program.
    - **scene** (number | string) - The scene value. For PC, it's a number; for Android/iOS, it's a string. Refer to the [scene values documentation](https://open.feishu.cn/document/uYjL24iN/uQzMzUjL0MzM14CNzMTN) for details.
    - **mode** (string) - The mini-program open mode (only returned for PC mini-programs).

### Request Example
```js
try {
    let result = tt.getLaunchOptionsSync();
    console.log(`getLaunchOptionsSync success: ${JSON.stringify(result)}`);
} catch (error) {
    console.log(`getLaunchOptionsSync fail: ${JSON.stringify(error)}`);
}
```

### Response Example
```json
{
    "path": "src/page/api/index",
    "scene": "1011",
    "query": {
      "foo": "bar"
    }
}
```

### Notes
- When opening a mini-program via Applink, you can customize the launch page path (`path`) and launch parameters (`query`).
- This method can only retrieve parameters for cold starts. For hot start parameters, read the parameters passed in the `App.onShow` method.
- This method is only supported in mini-programs. Check the client version support table for details.
```

--------------------------------

### Get HRBP List Example

Source: https://open.larkoffice.com/document/corehr-v1/authorization/list-2

This is an example of a successful response when retrieving the HRBP list. It includes HRBP and department IDs, pagination information, and a success status.

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "department_id": "4719456877659520852",
                "hrbp_id": "4719456877659520852"
            }
        ],
        "page_token": "eVQrYzJBNDNONlk4VFZBZVlSdzlKdFJ4bVVHVExENDNKVHoxaVdiVnViQT0=",
        "has_more": true
    }
}
```

--------------------------------

### Download and Unzip Example Code (Mac/Linux)

Source: https://open.larkoffice.com/document/quickly-create-a-login-free-web-app/start-the-local-service

Use curl to download the example code and unzip it. Navigate to the Python directory.

```Shell
curl https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/8841fb595ea110a900ef092f52e80fd0_VFYrhlOpLw.zip -o web_app_with_auth.zip
unzip web_app_with_auth.zip
cd web_app_with_auth/python
```

--------------------------------

### Get Messages by Card Request Example

Source: https://open.larkoffice.com/document/mail-v1/user_mailbox-message/get_by_card

This example demonstrates how to construct a GET request to retrieve messages associated with a specific email card. Ensure you replace placeholders like :user_mailbox_id, card_id, and owner_id with actual values. The Authorization header must be correctly formatted with a valid access token.

```http
GET https://open.feishu.cn/open-apis/mail/v1/user_mailboxes/:user_mailbox_id/messages/get_by_card?card_id=512ca581-6059-4449-8150-5522e6641d32&owner_id=1234567890
Host: open.feishu.cn
Authorization: Bearer u-7f1bcd13fc57d46bac21793a18e560
```

--------------------------------

### Get Attachment Details

Source: https://open.larkoffice.com/document/task-v2/attachment/get

Retrieves the details of a specific attachment using its GUID.

```APIDOC
## GET /task/v2/attachments/:attachment_guid

### Description
Provides a GUID for an attachment and returns its detailed information, including GUID, name, size, upload time, and a temporary downloadable link.

**Note**: Accessing attachment details requires read permissions for the resource the attachment belongs to.

### Method
GET

### Endpoint
https://open.feishu.cn/open-apis/task/v2/attachments/:attachment_guid

### Parameters
#### Path Parameters
- **attachment_guid** (string) - Required - The GUID of the attachment for which to retrieve details. This can be obtained by creating an attachment via the [Upload Attachment](https://open.feisu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/attachment/upload) interface or by querying through the [List Attachments](https://open.feisu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/attachment/list) interface.
  * Example: "b59aa7a3-e98c-4830-8273-cbb29f89b837"

#### Query Parameters
- **user_id_type** (string) - Optional - The type of user ID. 
  * Example: "open_id"
  * Default: `open_id`

### Request Headers
- **Authorization** (string) - Required - `tenant_access_token` or `user_access_token`. Format: "Bearer `access_token`". Example: "Bearer u-7f1bcd13fc57d46bac21793a18e560"

### Response
#### Success Response (200)
- **code** (int) - Error code, non-zero indicates failure.
- **msg** (string) - Error description.
- **data** (-) -
  - **attachment** (attachment) -
    - **guid** (string) - Attachment GUID.
    - **file_token** (string) - Token for the attachment within the cloud document system.
    - **name** (string) - Attachment name.
    - **size** (int) - Attachment size in bytes.
    - **resource** (resource) -
      - **type** (string) - Resource type.
      - **id** (string) - Resource ID.
    - **uploader** (member) -
      - **id** (string) - Member ID.
      - **type** (string) - Member type.
      - **role** (string) - Member role.
    - **is_cover** (boolean) - Whether it is a cover image.
    - **uploaded_at** (string) - Upload timestamp (ms).
    - **url** (string) - Temporary download URL for the attachment, valid for 3 minutes and allows only 3 download attempts. Dynamically generated only when retrieving the attachment.

#### Response Example
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "attachment": {
            "guid": "f860de3e-6881-4ddd-9321-070f36d1af0b",
            "file_token": "boxcnTDqPaRA6JbYnzQsZ2doB2b",
            "name": "foo.jpg",
            "size": 62232,
            "resource": {
                "type": "task",
                "id": "e6e37dcc-f75a-5936-f589-12fb4b5c80c2"
            },
            "uploader": {
                "id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f",
                "type": "user",
                "role": "editor"
            },
            "is_cover": false,
            "uploaded_at": "1675742789470",
            "url": "https://example.com/download/authcode/?code=OWMzNDlmMjJmZThkYzZkZGJlMjYwZTI0OTUxZTE2MDJfMDZmZmMwOWVj"
        }
    }
}
```

### Error Handling
- **400** - **1470400**: Invalid request parameters. Check the `msg` in the response for specific reasons.
- **404** - **1470404**: Attachment does not exist or has been deleted. Verify if the attachment still exists.
- **500** - **1470500**: Server error. Retry the call with the same request. If errors persist, contact technical support.
- **403** - **1470403**: Insufficient permissions to get the attachment. Ensure the calling identity has the necessary permissions.
```

--------------------------------

### Button Group Example

Source: https://open.larkoffice.com/document/feishu-cards/feishu-card-cardkit/configure-card-variables

An example demonstrating how to configure an array of buttons. Each button includes text, type, multi-endpoint URLs for interaction, and a value for callback.

```json
[
  {
    "text": "button1", //按钮文本
    "type": "default", //按钮样式
    "multi_url": { //跳转交互的参数配置
      "url": "https://open.feishu.cn",
      "pc_url": "",
      "android_url": "",
      "ios_url": ""
    },
    "value": "callback1"//回传交互的回传参数配置
  },
  {
    "text": "button2",
    "type": "default",
    "multi_url": {
      "url": "https://open.feishu.cn",
      "pc_url": "",
      "android_url": "",
      "ios_url": ""
    },
    "value": "callback2"
  }
]
```

--------------------------------

### Get Approver Task List Example

Source: https://open.larkoffice.com/document/corehr-v1/process-form_variable_data/approver-task/list

This is an example of a successful response when retrieving a list of approver tasks. It includes pagination information and a list of tasks with their IDs and statuses.

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "page_token": "1",
        "has_more": true,
        "approver_list": [
            {
                "approver_id": "7410781046418966060",
                "process_id": "7410781046418966060",
                "approver_status": 1
            }
        ]
    }
}
```

--------------------------------

### Initialize API Client with Full Configuration

Source: https://open.larkoffice.com/document/server-side-sdk/python--sdk/invoke-server-api

Create an API client instance with comprehensive settings including App ID, App Secret, domain, timeout, app type, app ticket, token setting, cache, and log level. This is useful for advanced configurations.

```python
import lark_oapi as lark
client = lark.Client.builder() \
    .app_id("APP_ID") \
    .app_secret("APP_SECRET") \
    .domain(lark.FEISHU_DOMAIN) \
    .timeout(3) \
    .app_type(lark.AppType.ISV) \
    .app_ticket("xxxx") \
    .enable_set_token(False) \
    .cache(Cache()) \
    .log_level(lark.LogLevel.DEBUG) \
    .build()
```

--------------------------------

### Get Role Authorization Example

Source: https://open.larkoffice.com/document/hire-v1/recruitment-related-configuration/auth/get

This example demonstrates how to retrieve the authorization details for a given role ID. The response includes detailed information about the role's permissions and scopes.

```APIDOC
## GET /hire/v1/recruitment-related-configuration/auth

### Description
Retrieves the authorization configuration for a specific recruitment role.

### Method
GET

### Endpoint
/hire/v1/recruitment-related-configuration/auth

### Query Parameters
- **role_id** (string) - Required - The ID of the role to retrieve authorization for.

### Response
#### Success Response (200)
- **code** (integer) - The status code of the response.
- **msg** (string) - The message describing the response status.
- **data** (object) - The data payload containing role information.
  - **role** (object) - Details of the role.
    - **id** (string) - The unique identifier for the role.
    - **name** (object) - The name of the role in different languages.
      - **zh_cn** (string) - The name in Simplified Chinese.
      - **en_us** (string) - The name in English.
    - **description** (object) - The description of the role in different languages.
      - **zh_cn** (string) - The description in Simplified Chinese.
      - **en_us** (string) - The description in English.
    - **modify_time** (string) - The timestamp when the role was last modified.
    - **role_status** (integer) - The status of the role.
    - **role_type** (integer) - The type of the role.
    - **scope_of_application** (integer) - The scope of application for the role.
    - **has_business_management_scope** (boolean) - Indicates if the role has business management scope.
    - **socail_permission_collection** (object) - Social permission collection for the role.
      - **feature_permissions** (array) - List of feature permissions.
        - **id** (string) - The ID of the feature permission.
        - **name** (object) - The name of the feature permission.
          - **zh_cn** (string) - The name in Simplified Chinese.
          - **en_us** (string) - The name in English.
      - **management_permissions** (array) - List of management permissions.
        - **id** (string) - The ID of the management permission.
        - **name** (object) - The name of the management permission.
          - **zh_cn** (string) - The name in Simplified Chinese.
          - **en_us** (string) - The name in English.
      - **data_permissions** (array) - List of data permissions.
        - **id** (string) - The ID of the data permission.
        - **name** (object) - The name of the data permission.
          - **zh_cn** (string) - The name in Simplified Chinese.
          - **en_us** (string) - The name in English.
        - **select_status** (integer) - The selection status of the data permission.
      - **business_management_scopes** (array) - List of business management scopes.
        - **entity** (object) - The entity for the business management scope.
          - **code** (string) - The code of the entity.
          - **name** (object) - The name of the entity.
            - **zh_cn** (string) - The name in Simplified Chinese.
            - **en_us** (string) - The name in English.
        - **permission_groups** (array) - List of permission groups.
          - **permission_ids** (array) - List of permission IDs.
          - **scope_rule** (object) - The scope rule.
            - **rule_type** (integer) - The type of the rule.
    - **campus_permission_collection** (object) - Campus permission collection for the role.
      - **feature_permissions** (array) - List of feature permissions.
        - **id** (string) - The ID of the feature permission.
        - **name** (object) - The name of the feature permission.
          - **zh_cn** (string) - The name in Simplified Chinese.
          - **en_us** (string) - The name in English.
      - **management_permissions** (array) - List of management permissions.
        - **id** (string) - The ID of the management permission.
        - **name** (object) - The name of the management permission.
          - **zh_cn** (string) - The name in Simplified Chinese.
          - **en_us** (string) - The name in English.
      - **data_permissions** (array) - List of data permissions.
        - **id** (string) - The ID of the data permission.
        - **name** (object) - The name of the data permission.
          - **zh_cn** (string) - The name in Simplified Chinese.
          - **en_us** (string) - The name in English.
        - **select_status** (integer) - The selection status of the data permission.
      - **business_management_scopes** (array) - List of business management scopes.
        - **entity** (object) - The entity for the business management scope.
          - **code** (string) - The code of the entity.
          - **name** (object) - The name of the entity.
            - **zh_cn** (string) - The name in Simplified Chinese.
            - **en_us** (string) - The name in English.
        - **permission_groups** (array) - List of permission groups.
          - **permission_ids** (array) - List of permission IDs.
          - **scope_rule** (object) - The scope rule.
            - **rule_type** (integer) - The type of the rule.

### Response Example
```json
{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "role": {
            "id": "6930815272790114324",
            "name": {
                "zh_cn": "招聘 HRBP",
                "en_us": "Recruitment HRBP"
            },
            "description": {
                "zh_cn": "赋予HRBP的权限",
                "en_us": "Authority given to HRBP"
            },
            "modify_time": "1716535727510",
            "role_status": 1,
            "role_type": 1,
            "scope_of_application": 1,
            "has_business_management_scope": true,
            "socail_permission_collection": {
                "feature_permissions": [
                    {
                        "id": "10101000",
                        "name": {
                            "zh_cn": "查看人才",
                            "en_us": "View talent"
                        }
                    }
                ],
                "management_permissions": [
                    {
                        "id": "20101001",
                        "name": {
                            "zh_cn": "门店管理",
                            "en_us": "Store management"
                        }
                    }
                ],
                "data_permissions": [
                    {
                        "id": "30203005",
                        "name": {
                            "zh_cn": "私密备注",
                            "en_us": "Private notes"
                        },
                        "select_status": 0
                    }
                ],
                "business_management_scopes": [
                    {
                        "entity": {
                            "code": "application",
                            "name": {
                                "zh_cn": "投递",
                                "en_us": "Application"
                            }
                        },
                        "permission_groups": [
                            {
                                "permission_ids": [
                                    "6930815272790114324"
                                ],
                                "scope_rule": {
                                    "rule_type": 1
                                }
                            }
                        ]
                    }
                ]
            },
            "campus_permission_collection": {
                "feature_permissions": [
                    {
                        "id": "10101002",
                        "name": {
                            "zh_cn": "查看投递",
                            "en_us": "View application"
                        }
                    }
                ],
                "management_permissions": [
                    {
                        "id": "20101002",
                        "name": {
                            "zh_cn": "编辑权限",
                            "en_us": "Edit permissions"
                        }
                    }
                ],
                "data_permissions": [
                    {
                        "id": "30103001",
                        "name": {
                            "zh_cn": "操作记录",
                            "en_us": "Action history"
                        },
                        "select_status": 0
                    }
                ],
                "business_management_scopes": [
                    {
                        "entity": {
                            "code": "application",
                            "name": {
                                "zh_cn": "投递",
                                "en_us": "application"
                            }
                        },
                        "permission_groups": [
                            {
                                "permission_ids": [
                                    "6930815272790114324"
                                ],
                                "scope_rule": {
                                    "rule_type": 0
                                }
                            }
                        ]
                    }
                ]
            }
        }
    }
}
```

### Error Handling
- **500 Internal Server Error**
  - **1002001**: System error. Please locate based on the actual error message or [contact customer service](https://applink.feishu.cn/client/helpdesk/open?id=6626260912531570952&extra=%7B%22channel%22:14,%22created_at%22:1614493146,%22scenario_id%22:6885151765134622721,%22signature%22:%22ca94c408b966dc1de2083e5bbcd418294c146e98%22%7D).
- **400 Bad Request**
  - **1002002**: Parameter error. Please check if the parameters are correct, such as type or size.
  - **1002352**: Role does not exist. Please check if the input parameter `role_id` is correct. `role_id` can be obtained through the [Get Role List](https://open.feishu.cn/document/ukTMukTMukTM/uMzM1YjLzMTN24yMzUjN/hire-v1/role/list) interface.
```
Tokens:
Raw