# 创建电子表格

在云空间指定目录下创建电子表格。可自定义表格标题。不支持带内容创建表格。

**注意事项**：要基于模板创建电子表格，可先获取模板电子表格的 `spreadsheet_token` 作为文件 token，再调用[复制文件](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/copy)接口创建电子表格。

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/sheets/v3/spreadsheets
HTTP Method | POST
接口频率限制 | [20 次/分钟](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用**<br>开启任一权限即可 | 查看、评论、编辑和管理云空间中所有文件(drive:drive)<br>查看、评论、编辑和管理电子表格(sheets:spreadsheet)<br>创建电子表格(sheets:spreadsheet:create)

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`<br>或<br>`user_access_token`<br>**值格式**："Bearer `access_token`"<br>**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"

### 请求体

名称 | 类型 | 必填 | 描述
---|---|---|---
title | string | 否 | 表格标题<br>**示例值**："Sales sheet"<br>**数据校验规则**：<br>- 长度范围：`0` ～ `255` 字符
folder_token | string | 否 | 文件夹 token。你可通过以下两种方式获取文件夹的 token：<br>- 文件夹的 URL：https://sample.feishu.cn/drive/folder/==fldbcO1UuPz8VwnpPx5a92abcef==<br>- 调用开放平台接口获取：<br>- 调用[获取我的空间（root folder）元数据](https://open.feishu.cn/document/ukTMukTMukTM/ugTNzUjL4UzM14CO1MTN/get-root-folder-meta)接口获取根目录（即根文件夹）的 token。<br>- 继续调用[获取文件夹中的文件清单](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file/list)接口，获取根目录下文件夹的 token。<br>**提示**：要在知识库中创建电子表格，你需调用[创建知识空间节点](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/wiki-v2/space-node/create)接口，并选择表格（sheet）类型。<br>**示例值**："fldbcO1UuPz8VwnpPx5a92abcef"

### 请求体示例
```json
{
    "title": "Sales sheet",
    "folder_token": "fldbcO1UuPz8VwnpPx5a92abcef"
}
```

### cURL 请求示例

```bash
curl --location --request POST 'https://open.feishu.cn/open-apis/sheets/v3/spreadsheets' \
--header 'Authorization: Bearer u-3iqkd6KWzRLzNdXfeuCMEb' \
--header 'Content-Type: application/json' \
--data-raw '{
    "title":"sales sheet",
    "folder_token":"fldbcO1UuPz8VwnpPx5a92abcef"
}'
```

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
spreadsheet | spreadsheet | 电子表格的基础信息
title | string | 电子表格标题
folder_token | string | 文件夹 token
url | string | 电子表格的 URL 链接
spreadsheet_token | string | 电子表格 token

### 响应体示例
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "spreadsheet": {
            "title": "Sales sheet",
            "folder_token": "fldbcO1UuPz8VwnpPx5a92abcef",
            "url": "https://example.feishu.cn/sheets/Iow7sNNEphp3WbtnbCscPqabcef",
            "spreadsheet_token": "Iow7sNNEphp3WbtnbCscPqabcef"
        }
    }
}
```

### 错误码

HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
500 | 1315203 | Server Error | 服务内部错误，[详询客服](https://applink.feishu.cn/client/helpdesk/open?id=6626260912531570952)
400 | 1310204 | Wrong Request Body | 检查请求体参数, 参考响应体中的错误提示
400 | 1310213 | Permission Fail | 当前调用身份没有电子表格的阅读（获取相关接口）或编辑（创建、更新等相关接口）权限。请参考以下方式解决：<br>- 如果你使用的是 `tenant_access_token`，意味着当前应用没有电子表格的阅读或编辑权限。你需通过电子表格网页页面右上方 **「...」** -> **「...更多」** ->**「添加文档应用」** 入口为应用添加权限。<br>**说明**：在 **添加文档应用** 前，你需确保目标应用至少开通了一个云文档 [API 权限](https://open.feishu.cn/document/ukTMukTMukTM/uYTM5UjL2ETO14iNxkTN/scope-list)。否则你将无法在文档应用窗口搜索到目标应用。<br>![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/22c027f63c540592d3ca8f41d48bb107_CSas7OYJBR.png?height=1994&maxWidth=550&width=3278)<br>- 如果你使用的是 `user_access_token`，意味着当前用户没有电子表格的阅读或编辑权限。你需通过电子表格网页页面右上方 **分享** 入口为当前用户添加权限。<br>![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/3e052d3bac56f9441296ae22e2969d63_a2DEYrJup8.png?height=278&maxWidth=550&width=1383)<br>了解具体操作步骤或其它添加权限方式，参考[云文档常见问题 3](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN#16c6475a)。
400 | 1310235 | Retry Later | 稍后重试
500 | 1315201 | Server Error | 服务内部错误，[详询客服](https://applink.feishu.cn/client/helpdesk/open?id=6626260912531570952)
400 | 1310226 | Excess Limit | 超出限制，参考响应体中的错误提示