创建文档

创建文档类型为 docx 的文档。你可选择传入文档标题和文件夹。

Tip: - 应用频率限制：单个应用调用频率上限为每秒 3 次，超过该频率限制，接口将返回 HTTP 状态码 400 及错误码 99991400。当请求被限频，应用需要处理限频状态码，并使用指数退避算法或其它一些频控策略降低对 API 的调用速率。

• 该接口仅支持指定文档标题，不支持带内容创建文档。要基于模板创建文档，可先获取模板文档的 document_id 作为文件 token，再调用复制文件接口创建文档。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/docx/v1/documents
HTTP Method	POST
接口频率限制	特殊频控
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	docx:document 创建及编辑新版文档 docx:document:create 创建新版文档

请求头

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

请求体

名称	类型	必填	描述
folder_token	string	否	指定文档所在文件夹 的 Token。不传或传空表示根目录。了解如何获取文件夹 Token，参考如何获取云文档资源相关 Token。 提示： 若应用使用的是 tenant_access_token 权限，此处仅可指定应用创建的文件夹。 示例值："fldcnqquW1svRIYVT2Np6Iabcef"
title	string	否	文档标题，只支持纯文本 示例值："一篇新的文档" 数据校验规则： - 长度范围：1 ～ 800 字符

请求体示例

{
    "folder_token": "fldcnqquW1svRIYVT2Np6Iabcef",
    "title": "一篇新的文档"
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ document	document	新建文档的文档信息
└ document_id	string	文档的唯一标识。你可以将 https://sample.feishu.cn/docx/ 与该标识拼接，并将 sample 替换为实际域名，生成文档的 URL 链接。如 https://sample.feishu.cn/docx/doxbcmEtbFrbbq10nPNu8gabcef。
└ revision_id	int	文档版本 ID
└ title	string	文档标题
└ display_setting	document_display_setting	文档展示设置
└ show_authors	boolean	文档信息中是否展示文档作者
└ show_create_time	boolean	文档信息中是否展示文档创建时间
└ show_pv	boolean	文档信息中是否展示文档访问次数
└ show_uv	boolean	文档信息中是否展示文档访问人数
└ show_like_count	boolean	文档信息中是否展示点赞总数
└ show_comment_count	boolean	文档信息中是否展示评论总数
└ show_related_matters	boolean	文档信息中是否展示关联事项
└ cover	document_cover	文档封面
└ token	string	图片 token
└ offset_ratio_x	number(float)	展示视图在水平方向的偏移比例。其值为距离原图中心的水平方向偏移值 px / 原图宽度 px。 视图在原图中心时，该值为 0； 视图在原图右部分时，该值为正数； 视图在原图左部分时，改值为负数。
└ offset_ratio_y	number(float)	展示视图在垂直方向的偏移比例。其值为距离原图中心的垂直方向偏移值 px / 原图高度 px。 视图在原图中心时，该值为 0； 视图在原图上部分时，该值为正数； 视图在原图下部分时，改值为负数。

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "document": {
            "document_id": "doxcni6mOy7jLRWbEylaKKC7K88",
            "revision_id": 1,
            "title": "undefined"
        }
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	1770001	invalid param	确认传入的参数是否合法
404	1770002	not found	确认文档是否已被删除
400	1770003	resource deleted	确认资源是否已被删除
400	1770004	too many blocks in document	确认文档 Block 数量是否超上限
400	1770005	too deep level in document	确认文档 Block 层级是否超上限
400	1770006	schema mismatch	确认文档结构是否合法
400	1770007	too many children in block	确认指定 Block 的 Children 数量是否超上限
400	1770008	too big file size	确认上传的文件尺寸是否超上限
400	1770010	too many table column	确认表格列数是否超上限
400	1770011	too many table cell	确认表格单元格数量是否超上限
400	1770012	too many grid column	确认 Grid 列数量是否超上限
400	1770013	relation mismatch	图片、文件等资源的关联关系不正确。请确保在创建图片、文件块时，同时上传了相关图片或文件素材至对应的文档块中。详情参考文档常见问题 3 和 4
400	1770014	parent children relation mismatch	确认 Block 父子关系是否正确
400	1770015	single edit with multi document	确认 Block 所属文档与指定的 Document 是否相同
400	1770019	repeated blockID in document	确认 Document 中的 BlockID 是否有重复
400	1770020	operation denied on copying document	确认 Document 是否正在创建副本中
400	1770021	too old document	确认指定的 Document 版本是否过旧
400	1770022	invalid page token	确认查询参数中的 page_token 是否合法
400	1770024	invalid operation	确认操作是否合法
400	1770025	operation and block not match	确认指定 Block 应用对应操作是否合法
400	1770026	row operation over range	确认行操作下标是否越界
400	1770027	column operation over range	确认列操作下标是否越界
400	1770028	block not support create children	确认指定 Block 添加 Children 是否合法
400	1770029	block not support to create	确认指定 Block 是否支持创建
400	1770030	invalid parent children relation	确认指定操作其父子关系是否合法
400	1770031	block not support to delete children	确认指定 Block 是否支持删除 Children
400	1770033	raw content size exceed limited	纯文本内容大小超过限制
400	1770039	folder not found	当前文件夹不存在，请检查 folder token 是否填写正确
403	1770040	no folder permission	无权限在此文件夹下创建文档。你可参考云文档常见问题 3 为调用身份开通文件夹权限。
400	1770034	operation count exceed limited	当前请求中涉及单元格个数过多，请拆分成多次请求
400	1770036	folder locked	不支持在同一文件夹下并发创建文档，同一文件夹下请串行调用该接口
400	1770037	folder size exceeded limit	云空间文件夹内挂载数量超过限制
403	1770032	forbidden	确认操作者是否有该文档的权限。参考云文档常见问题 3 为调用身份开通文档权限
500	1771001	server internal error	服务器内部错误，请联系技术支持
500	1771006	mount folder failed	挂载文档到云空间文件夹失败。请检查是否错误地传入了 wiki_token 并重试。若仍无法解决请咨询技术支持。
500	1771002	gateway server internal error	网关服务内部错误，请联系技术支持
500	1771003	gateway marshal error	网关服务解析错误，请联系技术支持
500	1771004	gateway unmarshal error	网关服务反解析错误，请联系技术支持
503	1771005	system under maintenance	系统服务正在维护中，请重试或联系技术支持