# 文档概述
飞书文档是可多人实时编辑的在线文档。在飞书文档可以实时协同编辑，看到的永远都是最新版。文档中还可以@同事、添加评论、插入任务列表等多种类型的内容，岂止于文档，更是丰富的创作工具。
1. 支持开发者以用户身份调用文档 API，完成创建文档、编辑文档等操作。
2. 应用可以通过集成 API，来完成自动化生成报告、批量创建文档等业务场景的文档自动化工作。
## 名词解释
### 文档
文档是富文本内容的容器。每篇文档都有一个 docToken 作为唯一标识。
### docToken
docToken 是一篇文档的唯一标识，你可以从通过以下方式获取一篇文档的 docToken：
- 通过文档的 URL 获取：https://xxx.feishu.cn/docs/==doccnmPiiJWfj1uk8bV7N5SzXaa==
- 通过 [Folder API](https://open.feishu.cn/document/ukTMukTMukTM/uEjNzUjLxYzM14SM2MTN) 的返回值获取文档的 docToken
对于 content 和 batch_update 方法，需要传入 docToken 来指定要操作的文档，create 方法在成功创建一篇文档后，也会返回对应的 docToken。
### 文档数据结构
我们定义了 OpenAPI 专用的文档数据结构，便于开发者对文档内容进行解析或编辑。在开始使用 Docs API 前，建议先查看[文档数据结构概述](https://open.feishu.cn/document/ukTMukTMukTM/uAzM5YjLwMTO24CMzkjN)了解更多。
通过 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"
**字段权限要求（任选其一）**：
查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论和导出文档(docs:doc:readonly)
title | string | 文档的标题。
revision | int | 文档的版本号，用于确认协同更新的版本。
content | string | 文档的正文。
**结构说明**：参考[文档数据结构概述](https://open.feishu.cn/document/ukTMukTMukTM/uAzM5YjLwMTO24CMzkjN) 和 [文档数据结构参考](https://open.feishu.cn/document/ukTMukTMukTM/ukDM2YjL5AjN24SOwYjN)
### 方法列表
> “商店”代表 [应用商店应用](https://open.feishu.cn/document/home/app-types-introduction/overview)；“自建”代表 [企业自建应用](https://open.feishu.cn/document/home/app-types-introduction/overview)
**[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建
---|---|---|---|---
[创建文档](https://open.feishu.cn/document/ukTMukTMukTM/ugDM2YjL4AjN24COwYjN)
`POST` /open-apis/doc/v2/create | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论、编辑和管理文档(docs:doc) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[获取文档富文本内容](https://open.feishu.cn/document/ukTMukTMukTM/uUDM2YjL1AjN24SNwYjN)
`GET` /open-apis/doc/v2/:docToken/content | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论、编辑和管理文档(docs:doc) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[获取文档文本内容](https://open.feishu.cn/document/ukTMukTMukTM/ukzNzUjL5czM14SO3MTN)
`GET` /open-apis/doc/v2/:docToken/raw_content
> 获取文档的纯文本内容 | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论、编辑和管理文档(docs:doc) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[编辑文档内容](https://open.feishu.cn/document/ukTMukTMukTM/uYDM2YjL2AjN24iNwYjN)
`POST` /open-apis/doc/v2/:docToken/batch_update | 查看、评论、编辑和管理云空间中所有文件(drive:drive)
查看、评论、编辑和管理文档(docs:doc) | `tenant_access_token`
`user_access_token` | **✓** | **✓**