# Third-party approval definition overview

The Third-party approval definition API is used to connect an enterprise's existing approval system with the Feishu approval system. This connection is at the data layer only, meaning the enterprise does not need to revamp its existing approval system. By creating a third-party approval definition and setting access methods, callback URLs, and encryption keys for the third-party approval system, approval data from the third-party system can flow back and forth within Feishu approvals. This allows enterprise employees to view and handle all approval tasks seamlessly within Feishu.

## Instructions

The third-party approval definition is primarily used to define:

- Basic information such as the name, group, and visibility range of the third-party approval within the Feishu approval center after integration.
- The redirect link to the third-party approval initiation page. When an employee initiates an approval within Feishu, it essentially redirects to the third-party approval initiation page for the approval initiation process.
- The callback URL for the third-party approval, which is used to receive status changes of approvals within Feishu. For example, when an approver agrees to a third-party approval within the Feishu approval center, the system sends the "agreement" data to the third-party approval callback URL, and the third-party approval system can then set the corresponding approval to the agreed status.

The open platform provides development tutorials to help you understand how to integrate third-party approvals into the Feishu approval center and facilitate the data flow. For detailed information, see [Quickly Develop Third-Party Approvals](https://open.feishu.cn/document/home/quickly-develop-three-party-approvals/introduction).
To achieve seamless login on web pages within the approval mini-program, you can only use the [Seamless Login on Client-Side Web Pages (Old)](https://open.feishu.cn/document/uYjL24iN/ukTO4UjL5kDO14SO5gTN#782a5834) method.

## Field description

Name | Type | Description
---|---|---
approval_name | string | Three-party approval definition name.<br>- The internationalized text key (i.e. the key in the i18n_resources.texts parameter) is passed in here, and the value needs to be assigned in the i18n_resources.texts parameter in the Key:Value format.<br>- This parameter needs to start with @i18n@.<br>**Example value**: "@i18n@1"
approval_code | string | The third-party approval definition Code is the unique identifier of the approval definition. Specific description:<br>- If the system can match the passed value approval_code to an existing approval definition, calling this interface will update the corresponding approval definition.<br>- If the system cannot match any approval definition approval_code, a new approval definition will be created and the real approval_code of the new approval definition will be returned (not the value you passed in through this parameter).<br>**Example value**: "permission_test"
group_code | string | The approval group to which the approval definition belongs, which is user-defined. Specific instructions:<br>- If the group_code passed in does not currently exist, a new approval group will be created.<br>- If group_code already exists, the approval group name will be updated with group_name.<br>**Example value**: "work_group"
group_name | string | Approval group name. The internationalized text key (i.e. the key in the i18n_resources.texts parameter) is passed in here, and the value needs to be assigned in the i18n_resources.texts parameter in the Key:Value format. The parameter needs to start with @i18n@.<br>- If group_code does not currently exist, group_name is required, indicating a new approval group is created.<br>- If group_code exists, the group name will be updated. If it is not filled, the group name will not be updated. The approval definition group name on the approval initiation page comes from this field.<br>**Example value**: "@i18n@2"
description | string | Description of the approval definition. When the company employee initiates the approval later, the description will be displayed on the approval initiation page.<br>- The internationalized text key (i.e. the key in the i18n_resources.texts parameter) is passed in here, and the value needs to be assigned in the i18n_resources.texts parameter in the Key:Value format.<br>- This parameter needs to start with @i18n@.<br>**Example value**: "@i18n@2"
external | approval_create_external | Information related to the third-party approval.
biz_name | string | The list is used to indicate which third-party system the approval comes from.<br>**Note**:<br>- The internationalized copy Key (i.e. the Key in the i18n_resources.texts parameter) is passed in here, and it also needs to be assigned in the i18n_resources.texts parameter in the Key:Value format.<br>- The parameter needs to start with @i18n@.<br>- When assigning a value to this parameter in i18n_resources, there is no need to set the **from** prefix. The approval center will concatenate the **from** prefix by default.<br>**Example value**: "@i18n@3"
biz_type | string | Approval defines business categories.<br>**Example value**: "permission"
create_link_mobile | string | The link for initiating three-party approval on the mobile terminal.<br>- If this link is set, when the mobile terminal initiates the approval, it will jump to the three-party approval initiation page corresponding to the link.<br>- If this link is not set, the approval will not be displayed on the mobile terminal.<br>**Example value**: "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages/approval-form/index?id=9999"
create_link_pc | string | The link for initiating a three-party approval on the PC side.<br>- If this link is set, when the PC side initiates the approval, it will jump to the three-party approval initiation page corresponding to the link.<br>- If this link is not set, the approval will not be displayed on the PC side.<br>**Example value**: "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc/pages/create-form/index?id=9999"
support_pc | boolean | Whether approval instances, approval tasks, and approval copies should be displayed on the PC side.<br>- If the value is true, the PC list will display the instance information under this definition.<br>- If the value is false, the PC list will not display the instance information under this definition.<br>**Example value**: true
support_mobile | boolean | Whether approval instances, approval tasks, and approval copies should be displayed on the mobile side.<br>- If the value is true, the mobile list will display the instance information under this definition.<br>- If the value is false, the mobile list will not display the instance information under this definition.<br>**Example value**: true
support_batch_read | boolean | Whether batch read is supported<br>**Example value**: true
action_callback_url | string | The operation callback URL of the third-party system. After the task approver of the **pending approval** instance clicks to agree or reject the operation, the approval center calls this URL to notify the third-party system. For information about the callback address, see [Quick Approval Callback for Third-Party Approval](https://open.feishu.cn/document/ukTMukTMukTM/ukjNyYjL5YjM24SO2IjN/quick-approval-callback).<br>**Example value**: "http://www.feishu.cn/approval/openapi/instanceOperate"
action_callback_token | string | The token brought during the callback is used by the business system to verify that the request comes from the approval center.<br>**Example value**: "token1234"
action_callback_key | string | Request parameter encryption key. If this parameter is configured, the request parameters will be encrypted and the request needs to be decrypted after receiving the request. For the encryption and decryption algorithm, refer to [Associated External Option Description](https://open.feishu.cn/document/ukTMukTMukTM/uADM4QjLwADO04CMwgDN).<br>**Example value**: "sdjkljkx9lsadf110"
allow_batch_operate | boolean | Whether batch approval is supported. When the value is true, the approver can batch process multiple tasks when processing the approval tasks under this definition.<br>**Example value**: false
viewers | approval_create_viewers\[\] | Approval visible list, the maximum length of the list is 200. Only users in the approval visible list can see the approval on the approval initiation page. If this parameter is not passed a value, it means that no one can see it.
viewer_type | string | Visible person type<br>**Optional values**:<br>- TENANT：Visible within tenant<br>- DEPARTMENT：Specified department<br>- USER：Specified user<br>- NONE：Not visible to anyone<br>**Example value**: "USER"
viewer_user_id | string | When viewer_type is USER, the user ID must be specified.<br>**Example value**: "19a294c2"
viewer_department_id | string | When view_type is set to DEPARTMENT, the department ID must be specified.<br>**Example value**: "od-ac9d697abfa990b715dcc33d58a62a9d"
i18n_resources | i18n_resource\[\] | International copywriting
locale | string | language. Optional values ​​are:<br>- zh-CN: Chinese<br>- en-US: English<br>- ja-JP: Japanese<br>**Example value**: "zh-CN"<br>**Optional values**:<br>- zh-CN：Chinese<br>- en-US：English<br>- ja-JP：Japanese
texts | i18n_resource_text\[\] | The Key:Value of the text. The Key needs to start with @i18n@ and the Value must be passed in according to the requirements of each parameter.<br>**Description**: This field is mainly used to adapt to internationalization and allows texts in multiple languages ​​to be set at the same time. The approval center will use the matching text according to the actual user's current voice environment. If the user's current voice environment text is not set, the default language text will be used.
key | string | The text key needs to match the key of each parameter.<br>**Example value**: "@i18n@1"
value | string | Copy Value, that is, the parameter value corresponding to the copy Key.<br>**Example value**: "people"
is_default | boolean | Whether it is the default language. The default language needs to contain all the required copy Keys. If the non-default language Key does not exist, the default language will be used instead.<br>**Example value**: true

## Data example

```json
{
    "approval_name": "@i18n@1",
    "approval_code": "permission_test",
    "group_code": "work_group",
    "group_name": "@i18n@2",
    "external": {
        "create_link_pc": "https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9c90fc38e07a9101&path=pc%2Fpages%2Fcreate-form%2Findex%3Fid%3D9999",
        "create_link_mobile": "https://applink.feishu.cn/client/mini_program/open?appId=cli_9c90fc38e07a9101&path=pages%2Fapproval-form%2Findex%3Fid%3D9999",
        "support_pc": true,
        "support_mobile": true,
        "support_batch_read": false,
        "action_callback_url":"http://feishu.cn/approval/openapi/operate",
        "action_callback_token":"sdjkljkx9lsadf110",
        "action_callback_key":"gfdqedvsadfgfsd",
        "enable_mark_readed": false,
        "key": "",
        "token":""
    },
    "i18n_resources":[
     {
        "locale":"zh-CN",
        "is_default":true,
         "texts":[
             {
             "key": "@i18n@1",
             "value":"people"  
            },
            {
             "key": "@i18n@2",
             "value":"hr"  
            }
         ]
      }
    ],
    "viewers": [
        {
            "viewer_type": "TENANT"
        }
    ]
}
```