创建授予名单

POST

https://open.feishu.cn/open-apis/admin/v1/badges/{badge_id}/grants

通过该接口可以为特定勋章创建一份授予名单，一枚勋章下最多可创建1000份授予名单。

错误码

HTTP状态码	错误码	描述	排查建议
500	1051000	unknown server error	服务内部错误，请稍后重试
400	1051001	request contain invalid param	请求中包含非法参数
403	1051002	request to exceed authority	请求发生越权
400	1051200	grant name are duplicated	授予名单名称发生冲突
400	1051201	cannot exceed the max length limit of grant name	授予名单名称的长度超过限制
400	1051202	already choose all staff, cannot related other user entity	禁止为全员授予类型名单关联用户群体
400	1051204	reach the count limit of grant	授予名单数量达到上限
400	1051113	cannot find this badge	未找到该勋章的信息

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://open.feishu.cn/open-apis/admin/v1/badges//grants?user_id_type=&department_id_type=' \
--header 'Authorization;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "激励勋章的授予名单",
    "grant_type": 0,
    "time_zone": "Asia/Shanghai",
    "rule_detail": {
        "effective_time": "1649606400",
        "expiration_time": "1649692799",
        "anniversary": 1,
        "effective_period": 1
    },
    "is_grant_all": false,
    "user_ids": [
        "u273y71"
    ],
    "department_ids": [
        "h121921"
    ],
    "group_ids": [
        "g122817"
    ]
}'

响应示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "grant": {
            "id": "g_49Z7CQ",
            "badge_id": "m_qTR2HM",
            "name": "激励勋章的授予名单",
            "grant_type": 0,
            "time_zone": "Asia/Shanghai",
            "rule_detail": {
                "effective_time": "1649606400",
                "expiration_time": "1649692799",
                "anniversary": 1,
                "effective_period": 1
            },
            "is_grant_all": false,
            "user_ids": [
                "u273y71"
            ],
            "department_ids": [
                "h121921"
            ],
            "group_ids": [
                "g122817"
            ]
        }
    }
}

请求参数

Path 参数

badge_id

string

必需

勋章ID

示例值："m_DjMzaK"

数据校验规则：

长度范围：1 ～ 64 字符

Query 参数

user_id_type

string

可选

用户 ID 类型

示例值："open_id"

可选值有：

open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID
union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？
user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？
默认值：open_id

当值为 user_id，字段权限要求：

获取用户 user ID

department_id_type

string

可选

此次调用中使用的部门ID的类型。

示例值："open_department_id"

可选值有：

department_id：以自定义department_id来标识部门
open_department_id：以open_department_id来标识部门
默认值：open_department_id

Header 参数

Authorization

string

必需

tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560"

默认值:

Bearer {{access_token}}

Content-Type

string

必需

固定值："application/json; charset=utf-8"

默认值:

application/json; charset=utf-8

Body 参数application/json

name

string

必需

勋章下唯一的授予事项，最多100个字符。示例值："激励勋章的授予名单"

grant_type

integer

必需

授予名单类型示例值：0 可选值有： 0：手动选择有效期 1：匹配系统入职时间默认值：0 数据校验规则：取值范围：0 ～ 1

time_zone

string

必需

授予名单的生效时间对应的时区，用于检查RuleDetail的时间戳的取值是否规范，取值范围为TZ database name 示例值："Asia/Shanghai" 数据校验规则：最小长度：1 字符

rule_detail

object

规则详情

必需

effective_time

string

可选

开始生效的时间戳。1.手动设置有效期类型勋章，配置有效期限需要配置该字段；2.时间戳必须是所在时区当天的零点时间戳，如时区为Asia/Shanghai时区时的1649606400 示例值："1649606400"

expiration_time

string

可选

结束生效的时间戳。1.手动设置有效期类型勋章，配置有效期限需要配置该字段；2.最大值：不得超过effective_time+100 年；3.非永久有效：时间戳必须是所在时区当天的23:59:59时间戳，如时区为Asia/Shanghai时区时的1649692799；4.永久有效：传值为0即可示例值："1649692799"

anniversary

integer

可选

入职周年日。根据入职时间发放类型勋章，需要配置该字段。示例值：1 默认值：1 数据校验规则：取值范围：1 ～ 60

effective_period

integer

可选

is_grant_all

boolean

必需

是否授予给全员。1.为false时，需要关联1~500个用户群体。2.为true时，不可关联用户、用户组、部门。示例值：false 默认值：false

user_ids

array[string]

可选

授予的用户ID列表，授予名单列表接口返回结果中不返回该字段，只在详情接口返回示例值：[u273y71]

department_ids

array[string]

可选

授予的部门ID列表，授予名单列表接口返回结果中不返回该字段，只在详情接口返回示例值：[h121921]

group_ids

array[string]

可选

授予的用户组ID列表，授予名单列表接口返回结果中不返回该字段，只在详情接口返回示例值：[g122817]

示例

返回响应

🟢200成功

application/json

Body

code

integer

必需

msg

string

必需

data

object

必需

grant

object

授予名单的信息

必需

修改于 2023-02-03 10:02:31

获取勋章详情

删除授予名单

创建授予名单

错误码#

请求参数

返回响应

错误码