概述 - 飞书 API

飞书文档是可多人实时编辑的在线文档。在飞书文档可以实时协同编辑，看到的永远都是最新版。文档中还可以@同事、添加评论、插入任务列表等多种类型的内容，岂止于文档，更是丰富的创作工具。

支持开发者以用户身份调用文档 API，完成创建文档、编辑文档等操作。

应用可以通过集成 API，来完成自动化生成报告、批量创建文档等业务场景的文档自动化工作。

名词解释

文档

文档是富文本内容的容器。每篇文档都有一个 docToken 作为唯一标识。

docToken

docToken 是一篇文档的唯一标识，你可以从通过以下方式获取一篇文档的 docToken：

通过文档的 URL 获取：https://xxx.feishu.cn/docs/doccnmPiiJWfj1uk8bV7N5SzXaa

通过 Folder API 的返回值获取文档的 docToken

对于 content 和 batch_update 方法，需要传入 docToken 来指定要操作的文档，create 方法在成功创建一篇文档后，也会返回对应的 docToken。

文档数据结构

我们定义了 OpenAPI 专用的文档数据结构，便于开发者对文档内容进行解析或编辑。在开始使用 Docs API 前，建议先查看文档数据结构概述了解更多。
通过 content、batch_update 接口获取或写入的文档内容，都遵循这个数据结构。此外，当你尝试使用 batch_update 接口编辑文档内容时，如果其中一个请求出现错误，将不会对文档进行任何修改。

文档更新工作流

通过 create 接口创建文档时，由于创建时还没有其他的协同者，所以不需要考虑协同编辑的影响，可以直接传入 content 对文档进行简单的初始化。
在尝试编辑一篇现存的文档时，则需要考虑其他编辑者协同编辑的影响。由于我们采用了 index 来标记希望编辑的位置和区域，所以在通过 API 编辑文档的同时，线上其他编辑者的操作可能会造成 index 的位置发生变化。
为了解决这个问题，在提交内容前，你需要先通过 content 接口获取到当前的文档状态和信息，content 接口会返回一个 revision 字段（即文档的版本号），在后续提交变更时，需要将 revision 字段作为参数传入，文档服务端会自动计算协同变化，将更新的内容插入到正确的位置。

应用可以通过以下方法，来完成创建、读取、编辑文档的行为：
创建文档：documents.create
读取文档：documents.content
编辑文档：documents.batch_update

新建后编辑文档以及编辑一篇线上文档的工作流如下：

如果提交文档更新时附带的 revision 字段与当前文档最新的 revision 版本差距过大，这次提交就可能会失败，建议在进行文档编辑操作前，都先通过 content 接口，获取最新的版本信息。

资源：文档 Document

每个文档都有唯一 token 作为标识。

由于线上资源存在新老规范，文档 token 在部分接口中的命名可能为 doc_token, document_token, docToken，在调用时请仔细阅读接口文档，避免因命名问题导致报错。

字段说明

名称	类型	描述
document_token	string	一个文档的唯一标识。示例值："doccnULnB44EMMPSYa3rIb4eJCf"字段权限要求（任选其一）：查看、评论、编辑和管理云空间中所有文件查看、评论和导出文档
title	string	文档的标题。
revision	int	文档的版本号，用于确认协同更新的版本。
content	string	文档的正文。结构说明：参考文档数据结构概述和文档数据结构参考

方法列表

“商店”代表应用商店应用；“自建”代表企业自建应用

	方法 (API)	权限要求（满足任一）		访问凭证（选择其一）
创建文档`POST` /open-apis/doc/v2/create	查看、评论、编辑和管理云空间中所有文件查看、评论、编辑和管理文档	tenant_access_tokenuser_access_token	✓	✓
获取文档富文本内容`GET` /open-apis/doc/v2/:docToken/content	查看、评论、编辑和管理云空间中所有文件查看、评论、编辑和管理文档	tenant_access_tokenuser_access_token	✓	✓
获取文档文本内容`GET` /open-apis/doc/v2/:docToken/raw_content获取文档的纯文本内容	查看、评论、编辑和管理云空间中所有文件查看、评论、编辑和管理文档	tenant_access_tokenuser_access_token	✓	✓
编辑文档内容`POST` /open-apis/doc/v2/:docToken/batch_update	查看、评论、编辑和管理云空间中所有文件查看、评论、编辑和管理文档	tenant_access_tokenuser_access_token	✓	✓

概述

名词解释#

文档#

docToken#

文档数据结构#

文档更新工作流#

资源：文档 Document#

字段说明#

方法列表#