创建卡片实体

基于卡片 JSON 代码或卡片搭建工具搭建的卡片，创建卡片实体。用于后续通过卡片实体 ID（card_id）发送卡片、更新卡片等。

使用限制

• 本接口仅支持卡片 JSON 2.0 结构或卡片搭建工具搭建的新版卡片。
• 调用该接口时，不支持将卡片设置为独享卡片模式。即不支持将卡片 JSON 数据中的 update_multi 属性设置为 false。
• 一个卡片实体，仅支持发送一次。
• 卡片实体的有效期为 14 天。即创建卡片实体超出 14 天后，你将无法调用相关接口操作卡片。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/cardkit/v1/cards
HTTP Method	POST
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用	cardkit:card:write 创建与更新卡片

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

请求体

名称	类型	必填	描述
type	string	是	卡片类型。可选值： - card_json：由卡片 JSON 代码构建的卡片 - template：由卡片搭建工具搭建的卡片模板 示例值："card_json" 数据校验规则： - 长度范围：1 ～ 50 字符
data	string	是	卡片数据。需要与 type 指定的类型一致： - 若 type 为 card_json，则此处应传卡片 JSON 代码，并确保将其转义为字符串。仅支持卡片 JSON 2.0 结构，即你必须声明 schema 为 2.0 - 若 type 为 template，则此处应传卡片模板的数据，并确保将其转义为字符串。仅支持新版卡片。即在搭建工具中，卡片名称旁应有“新版”标识 示例值："请参考下文请求体示例" 数据校验规则： - 长度范围：1 ～ 3000000 字符

请求体示例

{  // type 为 card_json 时
  "type": "card_json",
  "data": "{\"schema\":\"2.0\",\"header\":{\"title\":{\"content\":\"项目进度更新提醒\",\"tag\":\"plain_text\"}},\"config\":{\"streaming_mode\":true,\"summary\":{\"content\":\"\"},\"streaming_config\":{\"print_frequency_ms\":{\"default\":70,\"android\":70,\"ios\":70,\"pc\":70},\"print_step\":{\"default\":1,\"android\":1,\"ios\":1,\"pc\":1},\"print_strategy\":\"fast\"}},\"body\":{\"elements\":[{\"tag\":\"markdown\",\"content\":\"截至今日，项目完成度已达80%\",\"element_id\":\"markdown_1\"}]}}"
}


{  // type 为 template 时
  "type": "template",
  "data": "{\"template_id\":\"AAqIi1B8abcef\",\"template_version_name\":\"1.0.0\",\"template_variable\":{\"open_id\":\"ou_5c6d1637498e704f541095bba3dabcef\"}}}"
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ card_id	string	创建的卡片实体 ID。后续可通过发送消息接口传入卡片实体 ID 发送卡片。

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "card_id": "7355372766134157313"
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	10002	Your request contains an invalid request parameter.	参数错误。请根据接口返回的错误信息并参考文档检查输入参数。
400	200860	Card content exceeds limit.	卡片体积超限。建议卡片大小控制在 30KB 以内。
400	300301	Duplicate element_id in card component.	卡片内部组件 ID （即 element_id）重复。请检查并修改。
400	300302	update_multi property is false	卡片全局属性 update_multi 设置为了 false。在流式更新模式下，卡片全局属性 update_multi 需设置为 true。
400	300303	Only schema 2.0 is supported	该接口仅支持 JSON 2.0 结构。详情参考卡片 JSON 2.0 结构。
400	200220	Failed to generate card content	生成卡片内容失败。请检查卡片 JSON 格式是否有误。
400	300305	The number of card components exceeds 200	超出卡片组件限制。卡片 JSON 2.0 结构中，一张卡片最多支持 200 个元素（如 tag 为 plain_text 的文本元素）或组件。请将组件和元素的数量之和控制在 200 个以内。
400	300307	The card DSL is empty	卡片 JSON 数据为空。请检查并修改。