2025-12-17 15:50:12 +08:00

190 KiB

Raw Blame History

概述

最后更新：2025/07/16

企业和开发者通过文档接口可以便捷地新建文档和表格，将项目进展、业务数据等通知给成员，提高信息流转效率；也可通过文档接口新建智能表格（目前仅支持企业新建），邀请成员协作编辑，与业务系统结合更紧密；还可通过接口新建收集表，收集员工信息。调用接口的应用自动成为文档创建者，所建的文档、表格和收集表，仅应用可编辑内容；所建的智能表格，应用和成员均可编辑内容，内容也可被应用获取。创建后，应用可通过接口管理文档，也可指定成员作为文档管理员辅助管理。

提示

应用仅可读取和编辑自己创建的文档，无法编辑成员创建的文档；应用通过接口创建文档后，即可获得docid。docid仅在创建时返回，需要开发者妥善保存。

接口创建文档表现

接口创建的文档和收集表将在文档应用中标识出应用创建的信息，文档图标也将替换为应用图标。
接口创建的文档和收集表可添加企业成员进入通知范围，仅应用可编辑文档内容，成员无法编辑，但指定的管理员可以修改通知范围和获取收集表数据。
通过接口创建、修改、删除文档或收集表后，文档应用将自动向文档或收集表相关成员推送通知。

接口创建智能表格的表现

接口创建的智能表格将在智能表格中标识出应用创建的信息。
应用自动加入智能表格，成员可查询应用信息。
成员首次编辑智能表格时，展示应用可获取编辑内容提示。

配置可调用文档接口的应用

应用在调用文档接口前，需要先获得文档的使用权限。

自建应用 登录企业微信管理端，进入「协作」-「文档」-「API」，配置「可调用接口的应用」。 第三方应用 第三方服务商创建应用的时候，需要开启“文档接口权限”，企业授权安装第三方应用之后，第三方应用即拥有了调用文档接口的权限 代开发应用 第三方服务商为企业配置代开发应用时，需要开启「文档接口权限」，企业管理员确认之后，应用即拥有文档权限。

频率控制

对于 OpenAPI 的频率控制，我们使用维度加频率的描述方式如下：

维度	限制频率（次 / 分钟）
fileID	150
openID	300

这代表着当前 API 对于每个一篇文档的限制是每分钟 150 次，对于每个 openID（每个用户）的调用限制是每分钟 300 次。

#对文件操作的频率控制约定

对于文件操作（如新建文件、智能表格新建子表），如无特殊说明频率限制如下：

维度	限制频率（次 / 分钟）
openID	300

频控标签为：

openID

300

对于导入接口：

openID

对于导出接口：

维度	限制频率（次 / 天）
openID	9

#对于文档操作的频率控制约定

对于单篇文档的内容操作（如表格中添加一行数据），如无特殊说明频率限制如下：

维度	限制频率（次 / 分钟）
fileID	150

频控标签为：

fileID

150

获取access_token

最后更新：2024/03/26

注意

为了安全考虑，开发者请勿将 access_token 返回给前端，需要开发者保存在后台，所有访问企业微信api的请求由后台发起

获取access_token是调用企业微信API接口的第一步，相当于创建了一个登录凭证，其它的业务API接口，都需要依赖于access_token来鉴权调用者身份。因此开发者，在使用业务接口前，要明确access_token的颁发来源，使用正确的access_token。

请求方式： GET（HTTPS） 请求地址： https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET

提示

此处标注大写的单词 ID 和 SECRET，为需要替换的变量，根据实际获取值更新。其它接口也采用相同的标注，不再说明。

参数说明：

参数	必须	说明
corpid	是	企业ID，获取方式参考：术语说明-corpid
corpsecret	是	应用的凭证密钥，注意应用需要是启用状态，获取方式参考：术语说明-secret

权限说明： 每个应用有独立的secret，获取到的access_token只能本应用使用，所以每个应用的access_token应该分开来获取

返回结果：

{
   "errcode": 0,
   "errmsg": "ok",
   "access_token": "accesstoken000001",
   "expires_in": 7200
}

参数说明：

参数	说明
errcode	出错返回码，为0表示成功，非0表示调用失败
errmsg	返回码提示语
access_token	获取到的凭证，最长为512字节
expires_in	凭证的有效时间（秒）

注意事项： 开发者需要缓存access_token，用于后续接口的调用（注意：不能频繁调用gettoken接口，否则会受到频率拦截）。当access_token失效或过期时，需要重新获取。

access_token的有效期通过返回的expires_in来传达，正常情况下为7200秒（2小时）。由于企业微信每个应用的access_token是彼此独立的，所以进行缓存时需要区分应用来进行存储。 access_token至少保留512字节的存储空间。企业微信可能会出于运营需要，提前使access_token失效，开发者应实现access_token失效时重新获取的逻辑。

获取企业微信接口IP段

最后更新：2023/04/24

API域名IP即qyapi.weixin.qq.com的解析地址，由开发者调用企业微信端的接入IP。如果企业需要做防火墙配置，那么可以通过这个接口获取到所有相关的IP段。IP段有变更可能，当IP段变更时，新旧IP段会同时保留一段时间。建议企业每天定时拉取IP段，更新防火墙设置，避免因IP段变更导致网络不通。

**请求方式：**GET（HTTPS） 请求地址： https://qyapi.weixin.qq.com/cgi-bin/get_api_domain_ip?access_token=ACCESS_TOKEN （获取ACCESS_TOKEN）

请求参数说明：

参数	必须	说明
access_token	是	调用接口凭证

权限说明：

无限定。

返回结果：

{
    "ip_list":[
		"182.254.11.176",
		"182.254.78.66"
    ],
    "errcode":0,
    "errmsg":"ok"
}

返回参数说明：

参数	类型	说明
ip_list	StringArray	企业微信服务器IP段
errcode	int	错误码，0表示成功，非0表示调用失败
errmsg	string	错误信息，调用失败会有相关的错误信息返回

根据errcode值非0，判断调用失败。以下是access_token过期的返回示例：

{
    "ip_list":[],
    "errcode":42001,
    "errmsg":"access_token expired, hint: [1576065934_28_e0fae07666aa64636023c1fa7e8f49a4], from ip: 9.30.0.138, more info at https://open.work.weixin.qq.com/devtool/query?e=42001"
}

管理文档

新建文档

最后更新：2025/07/16

该接口用于新建文档、表格及智能表格，新建收集表可前往收集表管理查看。

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/create_doc?access_token=ACCESS_TOKEN

请求包体

{
	"spaceid": "SPACEID",
	"fatherid": "FATHERID",
	"doc_type": 3,
	"doc_name": "DOC_NAME",
	"admin_users": ["USERID1", "USERID2", "USERID3"]
}

参数说明

参数	类型	是否必须	说明
spaceid	string	否	空间spaceid。若指定`spaceid`，则`fatherid`也要同时指定
fatherid	string	否	父目录fileid, 在根目录时为空间spaceid
doc_type	uint32	是	文档类型, 3:文档 4:表格 10:智能表格
doc_name	string	是	文档名字（注意：文件名最多填255个字符, 超过255个字符会被截断）
admin_users	string[]	否	文档管理员userid

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"url": "URL",
	"docid": "DOCID"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
url	string	新建文档的访问链接
docid	string	新建文档的docid。docid仅在创建时返回，需要开发者妥善保存

重命名文档

最后更新：2024/10/28

该接口用于对指定文档、表格、智能表格及收集表进行重命名。

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/rename_doc?access_token=ACCESS_TOKEN

请求包体

{
	"docid": "DOCID",
	"formid": "FORMID",
	"new_name": "NEW_NAME"
}

参数说明

参数	类型	是否必须	说明
docid	string	否	文档docid（docid、formid只能填其中一个），仅可修改应用自己创建的文档
formid	string	否	收集表id（docid、formid只能填其中一个），仅可修改应用自己创建的收集表
new_name	string	是	重命名后的文档名（注意：文档名最多填255个字符, 英文算1个, 汉字算2个, 超过255个字符会被截断）

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

删除文档

最后更新：2024/10/28

该接口用于删除指定文档、表格、智能表格及收集表进行重命名。

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/del_doc?access_token=ACCESS_TOKEN

请求包体

{
	"docid": "DOCID",
	"formid": "FORMID"
}

参数说明

参数	类型	是否必须	说明
docid	string	否	文档docid（docid、formid只能填其中一个），仅可删除应用自己创建的文档
formid	string	否	收集表id（docid、formid只能填其中一个），仅可删除应用自己创建的收集表

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

获取文档基础信息

最后更新：2024/05/30

该接口用于获取指定文档、表格、智能表格及收集表的基础信息。

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/get_doc_base_info?access_token=ACCESS_TOKEN

请求包体

{
	"docid": "DOCID"
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档docid

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"doc_base_info": {
		"docid": "DOCID",
		"doc_name": "DOC_NAME",
		"create_time": 1717071093,
		"modify_time": 1717071093,
		"doc_type": 3
	}
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
docid	string	文档docid
doc_name	string	文档名字
create_time	uint64	文档创建时间
modify_time	uint64	文档最后修改时间
doc_type	uint32	3: 文档 4: 表格 10:智能表格

分享文档

最后更新：2024/05/30

该接口用于获取文档、表格、智能表格及收集表的分享链接。

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/doc_share?access_token=ACCESS_TOKEN

请求包体

{
    "docid":"DOCID",
    "formid": "FORMID"
}

参数说明

参数	类型	是否必须	说明
docid	string	否	文档id（docid、formid只能填其中一个）

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限
只能访问该应用创建的文档

返回示例

{
    "errcode":0,
    "errmsg":"ok",
    "share_url":"URL1"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
share_url	string	文档分享链接

管理智能表格内容

添加子表

本接口用于在表格的某个位置添加一个智能表，该智能表不存在视图、记录和字段，可以使用 API 在该智能表中添加视图、记录和字段。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/add_sheet?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"properties": {
		"title": "智能表",
		"index": 3
	}
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
properties	object	否	智能表属性
properties.title	string	否	智能表标题
properties.index	int32	否	智能表下标

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"properties": {
		"title": "智能表",
		"index": 3,
		"sheet_id": "123abc"
	}
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
properties	object	智能表属性
properties.sheet_id	string	智能表 ID，创建子表时生成的 6 位随机 ID
properties.title	string	智能表标题
properties.index	int32	智能表下标

删除子表

本接口用于删除在线表格中的某个智能表。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/delete_sheet?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "123Abc"
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	删除的Smartsheet 子表 ID

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

更新子表

本接口用于修改表格中某个子表的标题。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/update_sheet?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"properties": {
		"sheet_id": "123abc",
		"title": "XXXX"
	}
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
properties.sheet_id	string	是	子表 ID
properties.title	string	否	子表标题

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

查询子表

本接口用于查询一篇在线表格中全部智能表信息。 请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_sheet?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "xxx",
	"need_all_type_sheet":true
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	否	指定子表ID查询
need_all_type_sheet	bool	否	获取所有类型子表。为true时可获取包含仪表盘和说明页在内的所有类型的子表

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"sheet_list": [
        {
            "sheet_id": "123abc",
            "title": "XXXX",
            "is_visible": true,
            "type":"smartsheet"
        },
        {
            "sheet_id": "456abc",
            "title": "仪表盘1",
            "is_visible": true,
            "type": "dashboard"
        },
        {
            "sheet_id": "789abc",
            "title": "如何搭建自己的智能表格",
            "is_visible": true,
            "type": "external"
        }
	]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
sheet_list	object[] 智能表信息
sheet_list.sheet_id	string	子表id
sheet_list.title	string	子表名称
sheet_list.is_visible	bool	子表是否可见
sheet_list.type	string	子表类型。"dashboard" 仪表盘。"external" 说明页，"smartsheet" 智能表

添加视图

本接口用于在 Smartsheet 中的某个子表里添加一个新视图。单表最多允许有200个视图。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/add_view?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "123Abc",
	"view_title": "XXX",
	"view_type": "VIEW_TYPE_GRID"
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	Smartsheet 子表ID
view_title	string	是	视图标题
view_type	string	是	视图类型。见ViewType
property_gantt	obect(GanttViewProperty)	否	甘特视图属性,添加甘特图时必填
property_calendar	object(CalendarViewProperty)	否	日历视图属性，添加日历视图时必填

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"view": {
		"view_id": "vFYZUS",
		"view_title": "XXX",
		"view_type": "VIEW_TYPE_GRID"
	}
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
view	object(View)	添加视图响应

参数详细说明

View

示例

{
	"view_id": "vabcde",
	"view_title": "默认视图",
	"view_type": "VIEW_TYPE_GRID"
}

视图信息：

参数名	类型	描述
view_id	string	视图 ID
view_title	string	视图标题
view_type	string	视图类型。见ViewType

ViewType

视图类型：

枚举类型	描述
VEW_UNKNOWN	未知类型视图，传递该值不合法
VIEW_TYPE_GRID	表格视图
VIEW_TYPE_KANBAN	看板视图
VIEW_TYPE_GALLERY	画册视图
VIEW_TYPE_GANTT	甘特视图
VIEW_TYPE_CALENDAR	日历视图

GanttViewProperty

甘特设置

参数名	类型	是否必须	描述
start_date_field_id	string	是	时间条起点字段ID，只允许日期类型(`FIELD_TYPE_DATE_TIME`)的字段ID
end_date_field_id	string	是	时间条终点字段ID，只允许日期类型(`FIELD_TYPE_DATE_TIME`)的字段ID

CalendarViewProperty

日历设置

参数名	类型	是否必须	描述
start_date_field_id	string	是	时间条起点字段ID，只允许日期类型(`FIELD_TYPE_DATE_TIME`)的字段ID
end_date_field_id	string	是	时间条终点字段ID，只允许日期类型(`FIELD_TYPE_DATE_TIME`)的字段ID

删除视图

本接口用于在 smartsheet 中的某个子表里删除若干个视图。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/delete_views?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "123Abc",
	"view_ids": [
		"VIEWID1", "VIEWID2"
	]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	Smartsheet 子表ID
view_ids	string[]	是	要删除的视图ID列表

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

更新视图

本接口用于更新 Smartsheet 中的某个视图。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/update_view?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "123Abc",
	"view_id": "VIEWID",
	"view_title": "XXX",
	"property": {
	}
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	Smartsheet 子表ID
view_id	string	是	视图ID
view_title	string	否	视图标题
property	object(ViewProperty)	否	视图的排序/过滤/分组/填色配置，详见ViewProperty

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"view": {
	}
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
view	object(View)	更新成功的视图内容

参数详细说明

View

示例

{
	"view_id": "vabcde",
	"view_title": "默认视图",
	"view_type": "VIEW_TYPE_GRID",
	"property": {
	}
}

视图信息：

参数名	类型	描述
view_id	string	视图 ID
view_title	string	视图标题
view_type	string	视图类型。见ViewType
property	object(ViewProperty)	视图属性

ViewProperty

示例

{
	"auto_sort": false,
	"sort_spec": {},
	"filter_spec": {},
	"group_spec": {},
	"is_field_stat_enabled": false,
	"field_visibility": {
		"f1gHSR": false,
		"fabcde": false
	},
	"frozen_field_count": 0,
	"color_config": {
		"conditions": [{
			"id": "4840474257",
			"type": "VIEW_COLOR_CONDITION_TYPE_CELL",
			"color": "chromeAmberLighten_5",
			"condition": {
				"field_id": "fRCjJz",
				"field_type": "FIELD_TYPE_TEXT",
				"operator": "OPERATOR_CONTAINS",
				"string_value": {
					"value": [
						"5555"
					]
				}
			}
		}]
	}
}

参数说明

参数名	类型	是否必须	描述
auto_sort	bool	否	记录变更后自动重新排序
sort_spec	object(SortSpec)	否	排序设置
group_spec	object(GroupSpec)	否	分组设置
filter_spec	object(FilterSpec)	否	过滤设置
is_field_stat_enabled	bool	否	是否使用数据统计
field_visibility	object	否	类似map。 key为字段ID, value为布尔值表示是否显示
frozen_field_count	int32	否	冻结列数量，从首列开始
color_config	object(ViewColorConfig)	否	填色设置

SortSpec

示例

{
	 "sort_infos": [
	 	{
			"field_id": "FIELDID1",
			"desc": false
		},
		{
			"field_id": "FIELDID2",
			"desc": true
		}
	 ]
}

参数说明

参数名	类型	是否必须	描述
sort_infos	object[]	否	参与排序的字段列表
sort_infos.field_id	string	是	字段id
sort_infoes.desc	bool	否	是否降序

GroupSpec

示例

{
	 "groups": [
	 	{
			"field_id": "FIELDID1",
			"desc": false
		},
		{
			"field_id": "FIELDID2",
			"desc": true
		}
	 ]
}

参数说明

参数名	类型	是否必须	描述
groups	object[]	否	参与分组的字段列表
groups.field_id	string	是	字段id
groups.desc	bool	否	是否降序

FilterSpec

示例

{
	"conjunction": "CONJUNCTION_AND",
	"conditions": [
	]
}

参数说明

参数名	类型	是否必须	描述
conjunction	string	是	多个conditions之间是以and(`CONJUNCTION_AND`)还是or(`CONJUNCTION_OR`)进行组合
conditions	object	是	判断条件

Condition

注：不同字段类型支持的筛选不同，需要根据智能表格不同字段类型实际支持的筛选条件进行组合

示例1 过滤FIELDID1字段包含文本hello world的记录

{
	"field_id": "FIELDID1",
	"operator": "OPERATOR_CONTAINS",
	"string_value": {
		"value": ["hello world"]
	}
}

示例2 过滤FIELDID2字段为用户USERID1的记录

{
	"field_id": "FIELDID2",
	"operator": "OPERATOR_IS",
	"user_value": {
		"value": ["USERID1"]
	}
}

示例3 过滤FIELDID3字段为日期2025年5月14日的记录

{
	"field_id": "FIELDID3",
	"field_type": "FIELD_TYPE_DATE_TIME",
	"operator": "OPERATOR_IS",
	"date_time_value": {
		"type": "DATE_TIME_TYPE_DETAIL_DATE",
		"value": [
			"1747152000000"
		]
	}
}

参数说明

参数名	类型	是否必须	描述
field_id	string	是	字段ID
field_type	stiring	是	字段类型
operator	string	是	判断类型。见Operator
string_value.value	string[]	否	文本、网址、电话、邮箱、地理位置、单选、多选等列类型使用。选项列为选项ID；其它为文本值
number_value.value	double	否	数字、进度列类型使用
bool_value.value	bool	否	复选框列类型使用
user_value.value	string[]	否	人员、创建人、最后编辑人列类型使用，值为成员ID
date_time_value	object(FilterDataTimeValue)	否	日期、创建时间、最后编辑时间列类型使用

Operator

筛选值判断操作类型	说明
OPERATOR_UNKNOWN	未知
OPERATOR_IS	等于
OPERATOR_IS_NOT	不等于
OPERATOR_CONTAINS	包含
OPERATOR_DOES_NOT_CONTAIN	不包含
OPERATOR_IS_GREATER	大于
OPERATOR_IS_GREATER_OR_EQUAL	大于或等于
OPERATOR_IS_LESS	小于
OPERATOR_IS_LESS_OR_EQUAL	小于或等于
OPERATOR_IS_EMPTY	为空
OPERATOR_IS_NOT_EMPTY	不为空

FilterDataTimeValue

参数名	类型	是否必须	描述
type	string	是	日期类型。见DateTimeType
value	string[]	是	具体日期值，type为具体日期(`DATE_TIME_TYPE_DETAIL_DATE`)

DateTimeType

日期值类型	说明
DATE_TIME_TYPE_DETAIL_DATE	具体时间
DATE_TIME_TYPE_TODAY	今天
DATE_TIME_TYPE_TOMORROW	明天
DATE_TIME_TYPE_YESTERDAY	昨天
DATE_TIME_TYPE_CURRENT_WEEK	本周
DATE_TIME_TYPE_LAST_WEEK	上周
DATE_TIME_TYPE_CURRENT_MONTH	本月
DATE_TIME_TYPE_THE_PAST_7_DAYS	过去 7 天内
DATE_TIME_TYPE_THE_NEXT_7_DAYS	接下来 7 天内
DATE_TIME_TYPE_LAST_MONTH	上月
DATE_TIME_TYPE_THE_PAST_30_DAYS	过去 30 天内
DATE_TIME_TYPE_THE_NEXT_30_DAYS	接下来 30 天内

ViewColorConfig

示例

{
	"conditions": [
	]
}

参数说明

参数名	类型	是否必须	描述
conditions	object	是	判断条件

ViewColorCondition

示例

{
	"id": "5599107762",
	"type": "VIEW_COLOR_CONDITION_TYPE_CELL",
	"color": "chromeOrangeLighten_5",
	"condition": {
		"field_id": "fMPZMg",
		"field_type": "FIELD_TYPE_NUMBER",
		"operator": "OPERATOR_IS",
		"number_value": {
			"value": 5
		}
	}
}

参数说明

参数名	类型	是否必须	描述
id	string	否	填色id，新增时不需要传入，更新时传入
type	string	是	填色类型,见(ViewColorConditionType)
color	string	是	颜色，见(ViewColor)
conditions	object	是	判断条件

ViewColorConditionType

填色类型	说明
VIEW_COLOR_CONDITION_TYPE_ROW	行
VIEW_COLOR_CONDITION_TYPE_COLUMN	列
VIEW_COLOR_CONDITION_TYPE_CELL	单元格

ViewColor

颜色值	描述
fillColorGray_5	灰色_5
accentBlueLighten_5	蓝色_5
chromeCyanLighten_5	青色_5
chromeMintLighten_5	薄荷色_5
chromeRedLighten_5	红色_5
chromeOrangeLighten_5	橙色_5
chromeAmberLighten_5	琥珀色_5
chromeVioletLighten_5	紫色_5
chromePinkLighten_5	粉色_5
fillColorGray_4	灰色_4
accentBlueLighten_4	蓝色_4
chromeCyanLighten_4	青色_4
chromeMintLighten_4	薄荷色_4
chromeRedLighten_4	红色_4
chromeOrangeLighten_4	橙色_4
chromeAmberLighten_4	琥珀色_4
chromeVioletLighten_4	紫色_4
chromePinkLighten_4	粉色_4
fillColorGray_3	灰色_3
accentBlueLighten_3	蓝色_3
chromeCyanLighten_3	青色_3
chromeMintLighten_3	薄荷色_3
chromeRedLighten_3	红色_3
chromeOrangeLighten_3	橙色_3
chromeAmberLighten_3	琥珀色_3
chromeVioletLighten_3	紫色_3
chromePinkLighten_3	粉色_3

查询视图

本接口用于获取 Smartsheet 中某个子表里全部视图信息。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_views?access_token=ACCESS_TOKEN

请求包体：

{
    "docid": "DOCID",
    "sheet_id": "ezPcdA",
    "view_ids": [
        "vPpw9C",
        "vfM2tt"
    ],
    "offset": 0,
    "limit": 1
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	Smartsheet 子表ID
view_ids	string[]	否	需要查询的视图 ID 数组
offset	uint32	否	偏移量，初始值为 0
limit	uint32	否	分页大小 , 每页返回多少条数据；当不填写该参数或将该参数设置为 0 时，如果总数大于 1000，一次性返回 1000 个视图，当总数小于 1000 时，返回全部视图；limit 最大值为 1000

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "total": 2,
    "has_more": true,
    "next": 1,
    "views": [
    ]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
total	uint32	符合筛选条件的视图总数
has_more	bool	是否还有更多项
next	uint32	下次下一个搜索结果的偏移量
views	Object	视图数据

参数详细说明

View

示例

{
    "view_id": "vabcde",
    "view_title": "默认视图",
    "view_type": "VIEW_TYPE_GRID"
}

视图信息：

参数名	类型	描述
view_id	string	视图 ID
view_title	string	视图标题
view_type	string	视图类型。见ViewType
property	object(ViewProperty)	视图属性

ViewType

视图类型：

枚举类型	描述
VEW_UNKNOWN	未知类型视图，传递该值不合法
VIEW_TYPE_GRID	表格视图
VIEW_TYPE_KANBAN	看板视图
VIEW_TYPE_GALLERY	画册视图
VIEW_TYPE_GANTT	甘特视图

ViewProperty

示例

{
    "auto_sort": false,
    "sort_spec": {},
    "filter_spec": {
    },
    "group_spec": {},
    "is_field_stat_enabled": false,
    "field_visibility": {
        "f1gHSR": false,
        "fabcde": false
    },
    "frozen_field_count": 0,
    "color_config": {
        "conditions": [{
            "id": "4840474257",
            "type": "VIEW_COLOR_CONDITION_TYPE_CELL",
            "color": "chromeAmberLighten_5",
            "condition": {
                "field_id": "fRCjJz",
                "field_type": "FIELD_TYPE_TEXT",
                "operator": "OPERATOR_CONTAINS",
                "string_value": {
                    "value": [
                        "5555"
                    ]
                }
            }
        }]
    }
}

参数说明

参数名	类型	描述
auto_sort	bool	记录变更后自动重新排序
sort_spec	object(SortSpec)	排序设置
gourp_spec	object(GroupSpec)	分组设置
filter_spec	object(FilterSpec)	过滤设置
is_field_stat_enabled	bool	是否使用数据统计
field_visibility	object	类似map。 key为字段ID, value为布尔值表示是否显示
frozen_field_count	int32	冻结列数量，从首列开始
color_config	object(ViewColorConfig)	填色设置

SortSpec

示例

{
     "sort_infos": [
        {
            "field_id": "FIELDID1",
            "desc": false
        },
        {
            "field_id": "FIELDID2",
            "desc": true
        }
     ]
}

参数说明

参数名	类型	描述
sort_infos	object[]	参与排序的字段列表
sort_infos.field_id	string	字段id
sort_infoes.desc	bool	是否降序

GroupSpec

示例

{
     "groups": [
        {
            "field_id": "FIELDID1",
            "desc": false
        },
        {
            "field_id": "FIELDID2",
            "desc": true
        }
     ]
}

参数说明

参数名	类型	描述
groups	object[]	参与分组的字段列表
groups.field_id	string	字段id
groups.desc	bool	是否降序

FilterSpec

示例

{
    "conjunction": "CONJUNCTION_AND",
    "conditions": [
    ]
}

参数说明

参数名	类型	描述
conjunction	string	多个conditions之间是以and(`CONJUNCTION_AND`)还是or(`CONJUNCTION_OR`)进行组合
conditions	object	判断条件

Condition

注：不同字段类型支持的筛选不同，需要根据智能表格不同字段类型实际支持的筛选条件进行组合

示例1 过滤FIELDID1字段包含文本hello world的记录

{
    "field_id": "FIELDID1",
    "field_type": "FIELD_TYPE_TEXT",
    "operator": "OPERATOR_CONTAINS",
    "string_value": {
        "value": [
            "hello world"
        ]
    }
}

示例2 过滤FIELDID2字段为用户USERID1的记录

{
    "field_id": "FIELDID2",
    "field_type": "FIELD_TYPE_USER",
    "operator": "OPERATOR_IS",
    "user_value": {
        "value": ["USERID1"]
    }
}

示例3 过滤FIELDID3字段为日期2025年5月14日的记录

{
    "field_id": "FIELDID3",
    "field_type": "FIELD_TYPE_DATE_TIME",
    "operator": "OPERATOR_IS",
    "date_time_value": {
        "type": "DATE_TIME_TYPE_DETAIL_DATE",
        "value": [
            "1747152000000"
        ]
    }
}

参数说明

参数名	类型	描述
field_id	string	字段ID
field_type	string	字段类型。见FieldType
operator	string	判断类型。见Operator
string_value.value	string[]	文本、网址、电话、邮箱、地理位置、单选、多选等列类型使用。选项列为选项ID；其它为文本值
number_value.value	double	数字、进度列类型使用
bool_value.value	bool	复选框列类型使用
user_value.value	string[]	人员、创建人、最后编辑人列类型使用，值为成员ID
date_time_value	object(FilterDataTimeValue)	日期、创建时间、最后编辑时间列类型使用

FieldType

字段类型	说明
FIELD_TYPE_TEXT	文本
FIELD_TYPE_NUMBER	数字
FIELD_TYPE_CHECKBOX	复选框
FIELD_TYPE_DATE_TIME	日期
FIELD_TYPE_IMAGE	图片
FIELD_TYPE_ATTACHMENT	文件
FIELD_TYPE_USER	人员
FIELD_TYPE_URL	链接
FIELD_TYPE_SELECT	多选
FIELD_TYPE_CREATED_USER	创建人
FIELD_TYPE_MODIFIED_USER	最后编辑人
FIELD_TYPE_CREATED_TIME	创建时间
FIELD_TYPE_MODIFIED_TIME	最后编辑时间
FIELD_TYPE_PROGRESS	进度
FIELD_TYPE_PHONE_NUMBER	电话
FIELD_TYPE_EMAIL	邮箱
FIELD_TYPE_SINGLE_SELECT	单选
FIELD_TYPE_LOCATION	地理位置

Operator

筛选值判断操作类型	说明
OPERATOR_UNKNOWN	未知
OPERATOR_IS	等于
OPERATOR_IS_NOT	不等于
OPERATOR_CONTAINS	包含
OPERATOR_DOES_NOT_CONTAIN	不包含
OPERATOR_IS_GREATER	大于
OPERATOR_IS_GREATER_OR_EQUAL	大于或等于
OPERATOR_IS_LESS	小于
OPERATOR_IS_LESS_OR_EQUAL	小于或等于
OPERATOR_IS_EMPTY	为空
OPERATOR_IS_NOT_EMPTY	不为空

FilterDataTimeValue

参数名	类型	描述
type	string	日期类型。见DateTimeType
value	string[]	是	具体日期值，type为具体日期(`DATE_TIME_TYPE_DETAIL_DATE`)时必填

DateTimeType

日期值类型	说明
DATE_TIME_TYPE_DETAIL_DATE	具体时间
DATE_TIME_TYPE_TODAY	今天
DATE_TIME_TYPE_TOMORROW	明天
DATE_TIME_TYPE_YESTERDAY	昨天
DATE_TIME_TYPE_CURRENT_WEEK	本周
DATE_TIME_TYPE_LAST_WEEK	上周
DATE_TIME_TYPE_CURRENT_MONTH	本月
DATE_TIME_TYPE_THE_PAST_7_DAYS	过去 7 天内
DATE_TIME_TYPE_THE_NEXT_7_DAYS	接下来 7 天内
DATE_TIME_TYPE_LAST_MONTH	上月
DATE_TIME_TYPE_THE_PAST_30_DAYS	过去 30 天内
DATE_TIME_TYPE_THE_NEXT_30_DAYS	接下来 30 天内

ViewColorConfig

示例

{
    "conditions": [
    ]
}

参数说明

参数名	类型	是否必须	描述
conditions	object	是	判断条件

ViewColorCondition

示例

{
    "id": "5599107762",
    "type": "VIEW_COLOR_CONDITION_TYPE_CELL",
    "color": "chromeOrangeLighten_5",
    "condition": {
        "field_id": "fMPZMg",
        "field_type": "FIELD_TYPE_NUMBER",
        "operator": "OPERATOR_IS",
        "number_value": {
            "value": 5
        }
    }
}

参数说明

参数名	类型	是否必须	描述
id	string	否	填色id，新增时不需要传入，更新时传入
type	string	是	填色类型,见(ViewColorConditionType)
color	string	是	颜色，见(ViewColor)
conditions	object	是	判断条件

ViewColorConditionType

填色类型	说明
VIEW_COLOR_CONDITION_TYPE_ROW	行
VIEW_COLOR_CONDITION_TYPE_COLUMN	列
VIEW_COLOR_CONDITION_TYPE_CELL	单元格

ViewColor

颜色值	描述
fillColorGray_5	灰色_5
accentBlueLighten_5	蓝色_5
chromeCyanLighten_5	青色_5
chromeMintLighten_5	薄荷色_5
chromeRedLighten_5	红色_5
chromeOrangeLighten_5	橙色_5
chromeAmberLighten_5	琥珀色_5
chromeVioletLighten_5	紫色_5
chromePinkLighten_5	粉色_5
fillColorGray_4	灰色_4
accentBlueLighten_4	蓝色_4
chromeCyanLighten_4	青色_4
chromeMintLighten_4	薄荷色_4
chromeRedLighten_4	红色_4
chromeOrangeLighten_4	橙色_4
chromeAmberLighten_4	琥珀色_4
chromeVioletLighten_4	紫色_4
chromePinkLighten_4	粉色_4
fillColorGray_3	灰色_3
accentBlueLighten_3	蓝色_3
chromeCyanLighten_3	青色_3
chromeMintLighten_3	薄荷色_3
chromeRedLighten_3	红色_3
chromeOrangeLighten_3	橙色_3
chromeAmberLighten_3	琥珀色_3
chromeVioletLighten_3	紫色_3
chromePinkLighten_3	粉色_3

添加字段

本接口用于在智能表中的某个子表里添加一列或多列新字段。单表最多允许有150个字段。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/add_fields?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "SHEETID",
	"fields": [{
		"field_title": "TITLE",
		"field_type": "FIELD_TYPE_TEXT"
	}]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	表格ID
fields	object [] (AddFiled)	是	字段详情

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"fields": [{
		"field_id": "FIELDID",
		"field_title": "TITLE",
		"field_type": "FIELD_TYPE_TEXT"
	}]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
fields	object [] (Filed)	字段详情

参数详细说明

AddField

字段信息：

注意

字段属性与字段类型是匹配的，一种字段类型对应一种字段属性

参数名	类型	是否必填	描述
field_title	string	是	字段标题
field_type	string	是	字段类型，见FieldType ，必须为原属性
property_number	object(NumberFieldProperty)	是	`数字` 类型的字段属性
property_checkbox	object(CheckboxFieldProperty)	否	`复选框` 类型的字段属性
property_date_time	object(DateTimeFieldProperty)	是	`日期` 类型的字段属性
property_attachment	object(AttachmentFieldProperty)	否	`文件` 类型的字段属性
property_user	object(UserFieldProperty)	否	`人员` 类型的字段属性
property_url	object(UrlFieldProperty)	是	`超链接` 类型的字段属性
property_select	object(SelectFieldProperty)	是	`多选` 类型的字段属性
property_created_time	object(CreatedTimeFieldProperty)	是	`创建时间` 类型的字段属性
property_modified_time	object(ModifiedTimeFieldProperty)	是	`最后编辑时间` 类型的字段属性
property_progress	object(ProgressFieldProperty)	是	`进度` 类型的字段属性
property_single_select	object(SingleSelectFieldProperty)	是	`单选` 类型的字段属性
property_reference	object(ReferenceFieldProperty)	是	`引用` 类型的字段属性
property_location	object(LocationFieldProperty)	是	`地理位置` 类型的字段属性
property_auto_number	object(AutoNumberFieldProperty)	是	`自动编号` 类型的字段属性
property_currency	object(CurrencyFieldProperty)	是	`货币` 类型的字段属性
property_ww_group	object(WwGroupFieldProperty)	否	`群` 类型的字段属性
property_percentage	object(PercentageFieldProperty)	否	`百分数` 类型的字段属性
property_barcode	object(BarcodeFieldProperty)	否	`条码` 类型的字段属性

FieldType

字段类型	说明
FIELD_TYPE_TEXT	文本
FIELD_TYPE_NUMBER	数字
FIELD_TYPE_CHECKBOX	复选框
FIELD_TYPE_DATE_TIME	日期
FIELD_TYPE_IMAGE	图片
FIELD_TYPE_ATTACHMENT	文件
FIELD_TYPE_USER	成员
FIELD_TYPE_URL	超链接
FIELD_TYPE_SELECT	多选
FIELD_TYPE_CREATED_USER	创建人
FIELD_TYPE_MODIFIED_USER	最后编辑人
FIELD_TYPE_CREATED_TIME	创建时间
FIELD_TYPE_MODIFIED_TIME	最后编辑时间
FIELD_TYPE_PROGRESS	进度
FIELD_TYPE_PHONE_NUMBER	电话
FIELD_TYPE_EMAIL	邮件
FIELD_TYPE_SINGLE_SELECT	单选
FIELD_TYPE_REFERENCE	关联
FIELD_TYPE_LOCATION	地理位置
FIELD_TYPE_CURRENCY	货币
FIELD_TYPE_WWGROUP	群
FIELD_TYPE_AUTONUMBER	自动编号
FIELD_TYPE_PERCENTAGE	百分数
FIELD_TYPE_BARCODE	条码

NumberFieldProperty

数字类型字段属性信息：

参数名	类型	描述
decimal_places	int(DecimalPlaces)	表示小数点的位数，即数字精度
use_separate	bool	是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000

CheckboxFieldProperty

复选框类型字段属性信息：

参数名	类型	描述
checked	bool	新增时是否默认勾选

DateTimeFieldProperty

日期类型字段属性信息：

参数名	类型	描述
format	string(Format)	设置日期格式
auto_fill	bool	新建记录时，是否自动填充时间

AttachmentFieldProperty

文件类型字段属性信息：

参数名	类型	描述
display_mode	string(DisplayMode)	设置日期格式

UserFieldProperty

成员类型字段属性信息：

参数名	类型	描述
is_multiple	bool	允许添加多个人员
is_notified	bool	添加人员时通知用户，关闭后不通知

UrlFieldProperty

超链接类型字段属性信息：

参数名	类型	描述
type	string(LinkType)	超链接展示样式

SelectFieldProperty

多选类型字段属性信息：

参数名	类型	描述
is_quick_add	bool	是否允许填写时新增选项，用户不需要设置该参数
options	object [] ](Option)	多选选项的格式设置

CreatedTimeFieldProperty

创建时间类型字段属性信息：

参数名	类型	描述
format	string(Format)	设置日期格式

ModifiedTimeFieldProperty

最后编辑时间类型字段属性信息：

参数名	类型	描述
format	string(Format)	设置日期格式

ProgressFieldProperty

进度类型字段属性信息：

参数名	类型	描述
decimal_places	int(DecimalPlaces)	小数位数

SingleSelectFieldProperty

单选类型字段属性信息：

参数名	类型	描述
is_quick_add	bool	是否允许填写时新增选项，用户不需要设置该参数
options	object [] (Option)	单选选项的格式设置

ReferenceFieldProperty

关联字段属性信息：

参数名	类型	描述
sub_id	string	关联的子表id，为空时，表示关联本子表
filed_id	string	关联的字段id
is_multiple	bool	是否允许多选
view_id	string	视图id

LocationFieldProperty

地理位置字段属性信息：

参数名	类型	描述
input_type	string(LocationInputType)	输入类型

LocationFieldProperty

地理位置字段属性信息：

参数名	类型	描述
input_type	string(LocationInputType)	输入类型

AutoNumberFieldProperty

自动编号字段属性信息：

参数名	类型	描述
type	string(NumberType)	输入类型
rules	object[] (NumberRule)	自定义规则
reformat_existing_record	bool	是否应用于已有编号

CurrencyFieldProperty

货币类型字段属性

参数名	类型	描述
currency_type	string(CurrencyType)	输入类型
decimal_places	int(DecimalPlaces)	表示小数点的位数，即数字精度
use_separate	bool	是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000

WwGroupFieldProperty

群类型的字段属性

参数名	类型	描述
allow_multiple	bool	是否允许多个群聊

PercentageFieldProperty

百分数类型的字段属性

参数名	类型	描述
decimal_places	int(DecimalPlaces)	表示小数点的位数，即数字精度
use_separate	bool	是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000

BarcodeFieldProperty

条码类型的字段属性

参数名	类型	描述
mobile_scan_only	bool	仅限手机扫描录入

删除字段

本接口用于删除智能表中的某个子表里的一列或多列字段。。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/delete_fields?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "SHEETID",
	"field_ids": [
		"FIELDID"
	]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	表格ID
field_ids	string[]	是	需要删除的字段id列表

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

更新字段

本接口用于更新智能中的某个子表里的一个或多个字段的标题和字段属性信息。

注意

该接口只能更新字段名、字段属性，不能更新字段类型。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/update_fields?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "SHEETID",
	"fields": [{
		"field_id": "FIELD_ID",
		"field_title": "TITLE",
		"field_type": "FIELD_TYPE_TEXT"
	}]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	表格ID
fields	object [](UpdateField)	是	字段详情

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"fields": [{
		"field_id": "FIELDID",
		"field_title": "TITLE",
		"field_type": "FIELD_TYPE_TEXT"
	}]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
fields	object [](Field)	字段详情

参数详细说明

UpdateField

字段信息：

注意

字段属性与字段类型是匹配的，一种字段类型对应一种字段属性更新时field_title和property_number至少需要传一个，field_title不能被更新为原值

参数名	类型	是否必填	描述
field_id	string	是	字段 ID，更新字段属性时需要填写该字段，但字段 ID 不能被更新
field_title	string	否	字段标题，需要更新为的字段标题
field_type	string	是	字段类型，见FieldType ，必须为原属性
property_text	object	否	`文本` 类型的字段属性为空
property_number	object(NumberFieldProperty)	否	`数字` 类型的字段属性
property_checkbox	object(CheckboxFieldProperty)	否	`复选框` 类型的字段属性
property_date_time	object(DateTimeFieldProperty)	否	`日期` 类型的字段属性
property_attachment	object(AttachmentFieldProperty)	否	`文件` 类型的字段属性
property_user	object(UserFieldProperty)	否	`人员` 类型的字段属性
property_url	object(UrlFieldProperty)	否	`超链接` 类型的字段属性
property_select	object(SelectFieldProperty)	否	`多选` 类型的字段属性
property_created_user	object	否	`创建人` 类型的字段属性为空
property_modified_user	object	否	`最后编辑人` 类型的字段属性为空
property_created_time	object(CreatedTimeFieldProperty)	否	`创建时间` 类型的字段属性
property_modified_time	object(ModifiedTimeFieldProperty)	否	`最后编辑时间` 类型的字段属性
property_progress	object(ProgressFieldProperty)	否	`进度` 类型的字段属性
property_single_select	object(SingleSelectFieldProperty)	否	`单选` 类型的字段属性
property_reference	object(PropertyReference)	否	`引用` 类型的字段属性
property_location	object(LocationFieldProperty)	否	`地理位置` 类型的字段属性
property_auto_number	object(AutoNumberFieldProperty)	否	`自动编号` 类型的字段属性
property_currency	object(CurrencyFieldProperty)	否	`货币` 类型的字段属性
property_ww_group	object(WwGroupFieldProperty)	否	`群` 类型的字段属性
property_percentage	object(PercentageFieldProperty)	否	`百分数` 类型的字段属性
property_barcode	object(BarcodeFieldProperty)	否	`条码` 类型的字段属性

查询字段

本接口用于获取智能表中某个子表下字段信息，该接口可以完成下面三种功能：获取全部字段信息、依据字段名获取对应字段、依据字段 ID 获取对应字段信息。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_fields?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "SHEETID",
	"offset": 0,
	"limit": 10
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	表格ID
view_id	string	否	视图 ID
field_ids	string []	否	由字段 ID 组成的 JSON 数组
field_titles	string []	否	由字段标题组成的 JSON 数组
offset	int	否	偏移量，初始值为 0
limit	int	否	分页大小 , 每页返回多少条数据；当不填写该参数或将该参数设置为 0 时，如果总数大于 1000，一次性返回 1000 个字段，当总数小于 1000 时，返回全部字段；limit 最大值为 1000

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"total": 1,
	"fields": [{
		"field_id": "ID1",
		"field_title": "TITLE1",
		"field_type": "FIELD_TYPE_TEXT"
	}]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
total	Object	字段总数
fields	object [](Field)	字段详情

参数详细说明

Field

字段信息：

注意

字段属性与字段类型是匹配的，一种字段类型对应一种字段属性

参数名	类型	描述
field_id	string	字段 ID
field_title	string	字段标题
field_type	string	字段类型，见FieldType
property_number	object(NumberFieldProperty)	`数字` 类型的字段属性
property_checkbox	object(CheckboxFieldProperty)	`复选框` 类型的字段属性
property_date_time	object(DateTimeFieldProperty)	`日期` 类型的字段属性
property_attachment	object(AttachmentFieldProperty)	`文件` 类型的字段属性
property_user	object(UserFieldProperty)	`人员` 类型的字段属性
property_url	object(UrlFieldProperty)	`超链接` 类型的字段属性
property_select	object(SelectFieldProperty)	`多选` 类型的字段属性
property_created_time	object(CreatedTimeFieldProperty)	`创建时间` 类型的字段属性
property_modified_time	object(ModifiedTimeFieldProperty)	`最后编辑时间` 类型的字段属性
property_progress	object(ProgressFieldProperty)	`进度` 类型的字段属性
property_single_select	object(SingleSelectFieldProperty)	`单选` 类型的字段属性
property_reference	object(PropertyReference)	`引用` 类型的字段属性
property_location	object(LocationFieldProperty)	`地理位置` 类型的字段属性
property_auto_number	object(AutoNumberFieldProperty)	`自动编号` 类型的字段属性
property_currency	object(CurrencyFieldProperty)	`货币` 类型的字段属性
property_ww_group	object(WwGroupFieldProperty)	`群` 类型的字段属性
property_percentage	object(PercentageFieldProperty)	`百分数` 类型的字段属性
property_barcode	object(BarcodeFieldProperty)	`条码` 类型的字段属性

FieldType

字段类型	说明
FIELD_TYPE_TEXT	文本
FIELD_TYPE_NUMBER	数字
FIELD_TYPE_CHECKBOX	复选框
FIELD_TYPE_DATE_TIME	日期
FIELD_TYPE_IMAGE	图片
FIELD_TYPE_ATTACHMENT	文件
FIELD_TYPE_USER	成员
FIELD_TYPE_URL	超链接
FIELD_TYPE_SELECT	多选
FIELD_TYPE_CREATED_USER	创建人
FIELD_TYPE_MODIFIED_USER	最后编辑人
FIELD_TYPE_CREATED_TIME	创建时间
FIELD_TYPE_MODIFIED_TIME	最后编辑时间
FIELD_TYPE_PROGRESS	进度
FIELD_TYPE_PHONE_NUMBER	电话
FIELD_TYPE_EMAIL	邮件
FIELD_TYPE_SINGLE_SELECT	单选
FIELD_TYPE_REFERENCE	关联
FIELD_TYPE_LOCATION	地理位置
FIELD_TYPE_FORMULA	公式
FIELD_TYPE_CURRENCY	货币
FIELD_TYPE_WWGROUP	群
FIELD_TYPE_AUTONUMBER	自动编号
FIELD_TYPE_PERCENTAGE	百分数
FIELD_TYPE_BARCODE	条码

NumberFieldProperty

数字类型字段属性信息：

参数名	类型	描述
decimal_places	int(DecimalPlaces)	表示小数点的位数，即数字精度
use_separate	bool	是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000

CheckboxFieldProperty

复选框类型字段属性信息：

参数名	类型	描述
checked	bool	新增时是否默认勾选

DateTimeFieldProperty

日期类型字段属性信息：

参数名	类型	描述
format	string(Format)	设置日期格式
auto_fill	bool	新建记录时，是否自动填充时间

AttachmentFieldProperty

文件类型字段属性信息：

参数名	类型	描述
display_mode	string(DisplayMode)	展示样式

UserFieldProperty

成员类型字段属性信息：

参数名	类型	描述
is_multiple	bool	允许添加多个人员
is_notified	bool	添加人员时通知用户，关闭后不通知

UrlFieldProperty

超链接类型字段属性信息：

参数名	类型	描述
type	string(LinkType)	超链接展示样式

SelectFieldProperty

多选类型字段属性信息：

参数名	类型	描述
is_quick_add	bool	是否允许填写时新增选项，用户不需要设置该参数
options	object [] ](Option)	多选选项的格式设置

CreatedTimeFieldProperty

创建时间类型字段属性信息：

参数名	类型	描述
format	string(Format)	设置日期格式

ModifiedTimeFieldProperty

最后编辑时间类型字段属性信息：

参数名	类型	描述
format	string(Format)	设置日期格式

ProgressFieldProperty

进度类型字段属性信息：

参数名	类型	描述
decimal_places	int(DecimalPlaces)	小数位数

SingleSelectFieldProperty

单选类型字段属性信息：

参数名	类型	描述
is_quick_add	bool	是否允许填写时新增选项，用户不需要设置该参数
options	object [] (Option)	单选选项的格式设置

ReferenceFieldProperty

关联字段属性信息：

参数名	类型	描述
sub_id	string	关联的子表id，为空时，表示关联本子表
filed_id	string	关联的字段id
is_multiple	bool	是否允许多选
view_id	string	视图id

LocationFieldProperty

地理位置字段属性信息：

参数名	类型	描述
input_type	string(LocationInputType)	输入类型

AutoNumberFieldProperty

自动编号字段属性信息：

参数名	类型	描述
type	string(NumberType)	输入类型
rules	object[] (NumberRule)	自定义规则
reformat_existing_record	bool	是否应用于已有编号

CurrencyFieldProperty

货币类型字段属性

参数名	类型	描述
currency_type	string(CurrencyType)	输入类型
decimal_places	int(DecimalPlaces)	表示小数点的位数，即数字精度
use_separate	bool	是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000

WwGroupFieldProperty

群类型的字段属性

参数名	类型	描述
allow_multiple	bool	是否允许多个群聊

PercentageFieldProperty

百分数类型的字段属性

参数名	类型	描述
decimal_places	int(DecimalPlaces)	表示小数点的位数，即数字精度
use_separate	bool	是否使用千位符，设置此属性后数字字段将以英文逗号分隔千分位，如 1,000

BarcodeFieldProperty

条码类型的字段属性

参数名	类型	描述
mobile_scan_only	bool	仅限手机扫描录入

DecimalPlaces

小数点后的位数：

数值	描述
-1	显示原值
0	代表整数
1	精确到小数点后一位（1.0）
2	精确到小数点后两位（1.00）
3	精确到小数点后三位（1.000）
4	精确到小数点后四位（1.0000）

Format

日期格式：

字符串	描述
yyyy"年"m"月"d"日"	2018 年 4 月 20 日
yyyy-mm-dd"	2018-04-20
yyyy/m/d	2018/4/20
m"月"d"日"	4 月 20 日
yyyy"年"m"月"d"日" dddd	2018 年 4 月 20 日星期五
yyyy"年"m"月"d"日" hh:mm	2018 年 4 月 20 日 14:00
yyyy-mm-dd hh:mm	2018-04-20 14:00
m/d/yyyy	4/20/2018
d/m/yyyy	20/4/2018

LinkType

超链接展示样式可选值：

样式	描述
LINK_TYPE_PURE_TEXT	文字
LINK_TYPE_ICON_TEXT	图标文字

Option

Option 参数：

参数名	类型	描述
id	string	选项 ID
text	string	要填写的选项内容
style	int(Style)	选项颜色

Style

选项颜色：

数值	描述
1	浅红1
2	浅橙1
3	浅天蓝1
4	浅绿1
5	浅紫1
6	浅粉红1
7	浅灰1
8	白
9	灰
10	浅蓝1
11	浅蓝2
12	蓝
13	浅天蓝2
14	天蓝
15	浅绿2
16	绿
17	浅红2
18	红
19	浅橙2
20	橙
21	浅黄1
22	浅黄2
23	黄
24	浅紫2
25	紫
26	浅粉红2
27	粉红

DisplayMode

展示样式

展示样式	说明
DISPLAY_MODE_LIST	列表样式
DISPLAY_MODE_GRID	宫格样式

LocationInputType

地理位置输入类型

地理位置输入类型	说明
LOCATION_INPUT_TYPE_MANUAL	手动输入
LOCATION_INPUT_TYPE_AUTO	自动定位

NumberType

自动编号类型

自动编号类型	说明
NUMBER_TYPE_INCR	自增数字类型
NUMBER_TYPE_CUSTOM	自定义类型

NumberRule

自动编号规则	类型		说明
type	stringNumberRuleType	规则类型
value	string	存放创建时间格式CreateTimeFormat 或固定字符，自增数字位数

CreateTimeFormat

格式	说明
YYYYMMDD	20240301
YYYYMM	202403
MMDD	0301
YYYY	2024
MM	03
DD	01

NumberRuleType

数字规则类型

数字规则类型	说明
NUMBER_RULE_TYPE_INCR	自增id
NUMBER_RULE_TYPE_FIXED_CHAR	固定字符
NUMBER_RULE_TYPE_TIME	创建时间

CurrencyType

货币符号

货币符号类型	说明
CURRENCY_TYPE_CNY	人民币
CURRENCY_TYPE_USD	美元
CURRENCY_TYPE_EUR	欧元
CURRENCY_TYPE_GBP	英镑
CURRENCY_TYPE_JPY	日元
CURRENCY_TYPE_KRW	韩元
CURRENCY_TYPE_HKD	港元
CURRENCY_TYPE_MOP	澳门元
CURRENCY_TYPE_TWD	新台币
CURRENCY_TYPE_AED	阿联酋迪拉姆
CURRENCY_TYPE_AUD	澳大利亚元
CURRENCY_TYPE_BRL	巴西雷亚尔
CURRENCY_TYPE_CAD	加拿大元
CURRENCY_TYPE_CHF	瑞士法郎
CURRENCY_TYPE_IDR	印尼卢比
CURRENCY_TYPE_INR	印度卢比
CURRENCY_TYPE_MXN	墨西哥比索
CURRENCY_TYPE_MYR	马来西亚林吉特
CURRENCY_TYPE_PHP	菲律宾比索
CURRENCY_TYPE_PLN	波兰兹罗提
CURRENCY_TYPE_RUB	俄罗斯卢布
CURRENCY_TYPE_SGD	新加坡元
CURRENCY_TYPE_THB	泰国铢
CURRENCY_TYPE_TRY	土耳其里拉
CURRENCY_TYPE_VND	越南盾

添加记录

本接口用于在 Smartsheet 中的某个子表里添加一行或多行新记录。单表最多允许有100000行记录，15000000个单元格。注意不能通过添加记录接口给创建时间、最后编辑时间、创建人和最后编辑人四种类型的字段添加记录。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/add_records?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "123Abc",
	"key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE",
	"records": [{
		"values": {
			"FIELD_TITLE": [{
				"type": "text",
				"text": "文本内容"
			}]
		}
	}]
}

或

{
	"docid": "DOCID",
	"sheet_id": "123Abc",
	"key_type": "CELL_VALUE_KEY_TYPE_FIELD_ID",
	"records": [{
		"values": {
			"FIELD_ID": [{
				"type": "text",
				"text": "文本内容"
			}]
		}
	}]
}

FIELD_TITLE和FIELD_ID需要替换为字段标题或者字段ID

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	Smartsheet 子表ID
key_type	string(CellValueKeyType)	否	返回记录中单元格的key类型，默认用标题
records	Object	是	需要添加的记录的具体内容组成的 JSON 数组

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "records": [
			
    ]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
records	Object	由添加成功的记录的具体内容组成的 JSON 数组

参数详细说明

CellValueKeyType

记录(CommonRecord 或 AddRecord)中key的类型

枚举类型	描述
CELL_VALUE_KEY_TYPE_FIELD_TITLE	key用字段标题表示
CELL_VALUE_KEY_TYPE_FIELD_ID	key用字段 ID 表示

AddRecord

添加记录：

参数名	类型	描述
values	Object	记录的具体内容，key 为字段标题或字段 ID ，value 详见(Value)

CommonRecord

在 Smartsheet 的某个表格中添加记录响应、更新记录请求和更新记录响应的通用参数：

参数名	类型	描述
record_id	string	记录 ID
values	Object	记录的具体内容，key 为字段标题或字段 ID ，value 详见(Value)

Value

各种类型的字段对应的单元格的值

字段类型	单元格值类型	描述
文本(FIELD_TYPE_TEXT)	Object
数字(FIELD_TYPE_NUMBER)	double
复选框(FIELD_TYPE_CHECKBOX)	bool
日期(FIELD_TYPE_DATE_TIME)	string(以毫秒为单位的unix时间戳)
图片(FIELD_TYPE_IMAGE)	Object
文件(FIELD_TYPE_ATTACHMENT)	Object
成员(FIELD_TYPE_USER)	Object
链接(FIELD_TYPE_URL)	Object	数组类型为预留能力，目前只支持展示一个链接，建议只传入一个链接
多选(FIELD_TYPE_SELECT)	Object
进度(FIELD_TYPE_PROGRESS)	double
电话(FIELD_TYPE_PHONE_NUMBER)	string
邮箱(FIELD_TYPE_EMAIL)	string
单选(FIELD_TYPE_SINGLE_SELECT)	Object
地理位置(FIELD_TYPE_LOCATION)	Object	长度不大于1的数组。
货币(FIELD_TYPE_CURRENCY)	double
百分数(FIELD_TYPE_PERCENTAGE)	double

CellTextValue

文本类型字段的单元值类型

参数名	类型	描述
type	string	内容为文本(值为`text`)、内容为链接(值为`url`)
text	string	单元格内容
link	string	当type时`url`时，表示链接跳转url

CellImageValue

参数名	类型	描述
id	string	图片 ID,自定义id
title	string	图片标题
image_url	string	图片链接，通过上传图片接口获取
width	int32	图片宽度
height	int32	图片高度

CellAttachmentValue

示例

{
	"doc_type": 2,
	"file_ext": "SMARTSHEET",
	"file_id": "FILEID",
	"file_type": "70",
	"file_url": "https://doc.weixin.qq.com/smartsheet/xxx",
	"name": "智能表格",
	"size": 3267
}

参数名	类型	描述
name	string	文件名
size	int32	文件大小
file_ext	string	文件扩展名。文件夹为空，文件为对应文件拓展名，收集表为FORM，文档为DOC，表格为SHEET，幻灯片为SLIDE，思维导图为MIND，流程图为FLOWCHART，智能表为SMARTSHEET
file_id	string	文件ID
file_url	string	文件url ，如果是微盘文档则通过获取分享链接获得，如果是文档，则为文档url
file_type	string	文件类型。文件夹为Folder，微盘文件为Wedrive，收集表为30，文档为50，表格是51，幻灯片为52，思维导图为54，流程图为55，智能表为70
doc_type	string	文件类型，用于区分文件夹和文件

CellUserValue

参数名	类型	描述
user_id	string	成员ID

CellUrlValue

数组类型为预留能力，目前只支持展示一个链接，建议只传入一个链接示例

{
	"link": "https://developer.work.weixin.qq.com/document/path/97392",
	"text": "企业微信开发者中心",
	"type": "url"
}

参数名	类型	描述
type	string	填`url`
text	string	链接显示文本
link	string	链接跳转url

Option

示例

{
	"id": "1"
}

参数名	类型	描述
id	string	选项ID，当选项存在时，通过ID识别选项，当需要新增选项，则不填写此字段
style	int(Style)	选项颜色。新增选项时填写
text	string	要填写的选项内容。新增选项时填写，已经存在时优先匹配已经存在的选项，否则会新增选项

CellLocationValue

示例

{
	"id": "14313005936863363130",
	"latitude": "23.10647",
	"longitude": "113.32446",
	"source_type": 1,
	"title": "广州塔"
}

参数名	类型	描述
source_type	uint32	填`1`，表示来源为`腾讯地图`。目前只支持腾讯地图来源
id	string	地点ID
latitude	string	纬度
longitude	string	经度
title	string	地点名称

删除记录

本接口用于删除 Smartsheet 的某个子表中的一行或多行记录。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/delete_records?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "123Abc",
	"record_ids": [
		"re9IqD",
		"rpS0P9"
	]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	Smartsheet 子表ID
record_ids	string[]	是	要删除的记录 ID

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

更新记录

本接口用于更新 Smartsheet 中的某个子表里的一行或多行记录。注意不能通过更新记录接口给创建时间、最后编辑时间、创建人和最后编辑人四种类型的字段更新记录。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/update_records?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "123Abc",
	"key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE",
	"records": [
	]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	Smartsheet 子表ID
key_type	string(CellValueKeyType)	否	返回记录中单元格的key类型
records	Object	是	由需要更新的记录组成的 JSON 数组

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "records": [
    ]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
records	Object	由更新成功的记录的具体内容组成的 JSON 数组

参数详细说明

CellValueKeyType

记录(CommonRecord)中key的类型

枚举类型	描述
CELL_VALUE_KEY_TYPE_FIELD_TITLE	key用字段标题表示
CELL_VALUE_KEY_TYPE_FIELD_ID	key用字段 ID 表示

UpdateRecord

参数名	类型	描述
record_id	string	记录 ID
values	Object	记录的具体内容，key 为字段标题或字段 ID ，value 详见(Value)

CommonRecord

参数名	类型	描述
record_id	string	记录 ID
values	Object	记录的具体内容，key 为字段标题或字段 ID ，value 详见(Value)

查询记录

本接口用于获取 Smartsheet 中某个子表下记录信息，该接口可以完成下面三种功能：获取全部记录信息、依据字段名和记录 ID 获取对应记录、对记录进行排序。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_records?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "123Abc",
	"view_id": "vCRl8n",
	"record_ids": [],
	"key_type": "CELL_VALUE_KEY_TYPE_FIELD_TITLE",
	"field_titles": [],
	"field_ids": [],
	"sort": [],
	"offset": 0,
	"limit": 100,
	"ver": 160,
	"filter_spec": {
		"conjunction": "CONJUNCTION_AND",
		"conditions": [{
			"field_id": "f53B4X",
			"field_type": "FIELD_TYPE_TEXT",
			"operator": "OPERATOR_CONTAINS",
			"string_value": {
				"value": [
					"123"
				]
			}
		}]
	}
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	Smartsheet 子表ID
view_id	string	否	视图 ID
record_ids	string[]	否	由记录 ID 组成的 JSON 数组
key_type	string(CellValueKeyType)	否	返回记录中单元格的key类型
field_titles	string[]	否	返回指定列，由字段标题组成的 JSON 数组，key_type 为 `CELL_VALUE_KEY_TYPE_FIELD_TITLE` 时有效
field_ids	string[]	否	返回指定列，由字段 ID 组成的 JSON 数组，key_type 为 `CELL_VALUE_KEY_TYPE_FIELD_ID` 时有效
sort	Object	否	对返回记录进行排序
offset	uint32	否	偏移量，初始值为 0
limit	uint32	否	分页大小 , 每页返回多少条数据；当不填写该参数或将该参数设置为 0 时，如果总数大于 1000，一次性返回 1000 行记录，当总数小于 1000 时，返回全部记录；limit 最大值为 1000
ver	uint32	否	版本号
filter_spec	object(FilterSpec)	否	过滤设置，不支持和sort一起使用

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok",
	   "ver":160
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
total	uint32	符合筛选条件的视图总数
has_more	bool	是否还有更多项
next	uint32	下次下一个搜索结果的偏移量
records	Object	由查询记录的具体内容组成的 JSON 数组
ver	uint32	版本号

参数详细说明

CellValueKeyType

记录(Record)中key的类型

枚举类型	描述
CELL_VALUE_KEY_TYPE_FIELD_TITLE	key用字段标题表示
CELL_VALUE_KEY_TYPE_FIELD_ID	key用字段 ID 表示

Sort

示例字段标题为文本列的降序排序，字段标题为数字列的升序序排序。需要一个Sort数组：

[
	{
		"field_title": "文本列",
		"desc": true
	},
	{
		"field_title": "数字列",
		"desc": false
	}
]

在 Smartsheet 的某个表格中对记录进行排序的参数：

参数名	类型	是否必须	描述
field_title	string	是	需要排序的字段标题
desc	bool	否	是否进行降序排序，默认值为 false

Record

Smartsheet 的某个表格中记录相关的参数： 示例1 按字段标题返回各行的单元格内容

{
    "record_id": "r5ud8u",
    "create_time": "1715846245084",
    "update_time": "1715846248810",
    "values": {
        "文本字段1-标题": [
            {
                "type": "text",
                "text": "XXXX"
            }
        ],
        "数字字段1-标题": 123
    },
    "creator_name":"NAME",
    "updater_name":"NAME"
}

示例2 按字段ID返回各行的单元格内容

{
    "record_id": "r5ud8u",
    "create_time": "1715846245084",
    "update_time": "1715846248810",
    "values": {
        "TextField1Id": [
            {
                "type": "text",
                "text": "XXXX"
            }
        ],
        "NumField1Id": 123
    },
		"creator_name":"NAME",
		"updater_name":"NAME"
}

参数名	类型	描述
record_id	string	记录 ID
create_time	string	记录的创建时间
update_time	string	记录的更新时间
values	Object	记录的具体内容，key 为字段标题或字段 ID ，value 详见(Value)
creator_name	string	创建者名字
updater_name	string	最后编辑者名字

Value

各种类型的字段对应的单元格的值

字段类型	单元格值类型	描述
文本(FIELD_TYPE_TEXT)	Object
数字(FIELD_TYPE_NUMBER)	double
复选框(FIELD_TYPE_CHECKBOX)	bool
日期(FIELD_TYPE_DATE_TIME)	string(以毫秒为单位的unix时间戳)
图片(FIELD_TYPE_IMAGE)	Object
文件(FIELD_TYPE_ATTACHMENT)	Object
成员(FIELD_TYPE_USER)	Object
链接(FIELD_TYPE_URL)	Object	数组类型为预留能力，目前只支持展示一个链接，建议只传入一个链接
多选(FIELD_TYPE_SELECT)	Object
进度(FIELD_TYPE_PROGRESS)	double
电话(FIELD_TYPE_PHONE_NUMBER)	string
邮箱(FIELD_TYPE_EMAIL)	string
单选(FIELD_TYPE_SINGLE_SELECT)	Object
地理位置(FIELD_TYPE_LOCATION)	Object	长度不大于1的数组。
关联(FIELD_TYPE_REFERENCE)	string []	关联的记录id
货币(FIELD_TYPE_CURRENCY)	double
自动编号(FIELD_TYPE_AUTONUMBER)	Object[](CellAutoNumberValue
百分数(FIELD_TYPE_PERCENTAGE)	double

CellTextValue

文本类型字段的单元值类型

参数名	类型	描述
type	string	内容为文本(值为`text`)、内容为链接(值为`url`)
text	string	单元格内容
link	string	当type时`url`时，表示链接跳转url

CellImageValue

参数名	类型	描述
id	string	图片 ID
title	string	图片标题
image_url	string	图片url
width	int32	图片宽度
height	int32	图片高度

CellAttachmentValue

示例

{
	"doc_type": 2,
	"file_ext": "SMARTSHEET",
	"file_type": "70",
	"file_url": "https://doc.weixin.qq.com/smartsheet/xxx",
	"name": "智能表格",
	"size": 3267
}

参数名	类型	描述
name	string	文件名
size	int32	文件大小
file_ext	string	文件扩展名
file_url	string	文件url
file_type	string	文件类型，文件夹为Folder，微盘文件为Wedrive，文件夹为Folder，微盘文件为Wedrive，收集表为30，文档为50，表格是51，幻灯片为52，思维导图为54，流程图为55，智能表为70
doc_type	string	接口返回的文件类型，1为文件夹，2为文件

CellUserValue

参数名	类型	描述
user_id	string	成员ID
tmp_external_userid	string	外部用户临时id，同一个用户在不同的智能表中返回的该id不一致。可进一步通过tmp_external_userid的转换接口转换成external_userid，方便识别外部用户的身份。

CellUrlValue

数组类型为预留能力，目前只支持展示一个链接，建议只传入一个链接示例

{
	"link": "https://developer.work.weixin.qq.com/document/path/97392",
	"text": "企业微信开发者中心",
	"type": "url"
}

参数名	类型	描述
type	string	填`url`
text	string	链接显示文本
link	string	链接跳转url

Option

示例

{
	"id": "1",
	"style": 1,
	"text": "one"
}

参数名	类型	描述
id	string	选项ID
style	uint32	选项颜色(Style)
text	string	选项内容

CellLocationValue

示例

{
	"id": "14313005936863363130",
	"latitude": "23.10647",
	"longitude": "113.32446",
	"source_type": 1,
	"title": "广州塔"
}

参数名	类型	描述
source_type	uint32	填`1`，表示来源为`腾讯地图`。目前只支持腾讯地图来源
id	string	地点ID
latitude	string	纬度
longitude	string	经度
title	string	地点名称

CellAutoNumberValue

示例

{
	"seq": "3",
	"text": "3"
}

参数名	类型	描述
seq	string	序号
text	string	展示的文本

添加编组

本接口用于在智能表中的某个子表里添加编组。单表最多允许有150个编组。每个编组最多允许有150个字段。字段只能同时存在于一个编组。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/add_field_group?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "SHEETID",
	"name":"编组名称",
	"children": [
		{
			"field_id": "field_id"
		},
		{
			"field_id": "field_id"
		}]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	表格ID
name	string	是	编组名称，不能和已有名称重复
children	object[]	否	编组内容
children.field_id	string	否	字段id

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"field_group": {
		"field_group_id": "FIELD_GROUP_ID",
		"name": "编组名称",
		"children": [{
				"field_id": "FIELD_ID"
			},
			{
				"field_id": "FIELD_ID"
			}
		]
	}
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
field_group	object	编组
field_group.field_group_id	string	编组id
field_group.name	string	编组名称
field_group.children	object[]	编组内容
field_group.children.field_id	string	字段id

删除编组

本接口用于删除智能表的某个子表中的一个或多个编组。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/delete_field_groups?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "123Abc",
	"field_group_ids": [
		"fgCLYCF",
		"fgCLYCM"
	]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	子表ID
field_group_ids	string[]	是	要删除的编组 ID

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

更新编组

本接口用于在智能表中的某个子表里更新已有编组。每个编组最多允许有150个字段。字段只能同时存在于一个编组。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/update_field_group?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "SHEETID",
	"field_group_id":"FIELD_GROUP_ID",
	"name":"编组名称",
	"children": [
		{
			"field_id": "FIELD_ID"
		},
		{
			"field_id": "FIELD_ID"
		}]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	表格ID
field_group_id	string	是	编组id
name	string	否	编组名称，不能和已有名称重复
children	object[]	否	编组内容
children.field_id	string	否	字段id

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"field_group": {
		"field_group_id": "FIELD_GROUP_ID",
		"name": "编组名称",
		"children": [{
				"field_id": "FIELD_ID"
			},
			{
				"field_id": "FIELD_ID"
			}
		]
	}
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
field_group_id	string	编组id
name	string	编组名称
children	object[]	编组内容
children.field_id	string	字段id

获取编组

本接口用于在智能表中的某个子表里获取已有的编组。

请求方式：POST(HTTPS) 请求地址：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/get_field_groups?access_token=ACCESS_TOKEN

请求包体：

{
	"docid": "DOCID",
	"sheet_id": "SHEETID",
	"offset":0,
	"limit":10
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档的docid
sheet_id	string	是	表格ID
offset	uint32	否	偏移量，初始值为 0
limit	uint32	否	分页大小 , 每页返回多少条数据

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"total": 1,
	"has_more": false,
	"next": 0,
	"field_groups": [{
		"field_group_id": "FIELD_GROUP_ID",
		"name": "编组名称",
		"children": [{
			"field_id": "FIELD_ID"
		}]
	}]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
total	uint32	编组数量
has_more	bool	是否还有更多数据
next	uint32	下一偏移位置
field_groups	obj[]	编组列表
field_groups.field_group_id	string	编组id
field_groups.name	string	编组名称
field_groups.children	object[]	编组内容
field_groups.children.field_id	string	字段id

设置文档权限

获取文档权限信息

最后更新：2024/05/30

该接口用于获取文档、表格、智能表格的查看规则、文档通知范围及权限、安全设置信息

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/doc_get_auth?access_token=ACCESS_TOKEN

请求包体

{
	"docid":"DOCID"
}

参数说明

参数	类型	是否必须	说明
docid	string	是	文档id

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限
只能访问该应用创建的文档

返回示例

{
    "errcode":0,
    "errmsg":"ok",
    "access_rule":{
        "enable_corp_internal":true,
        "corp_internal_auth":1,
        "enable_corp_external":true,
        "corp_external_auth":1,
        "corp_internal_approve_only_by_admin":true,
        "corp_external_approve_only_by_admin":true,
        "ban_share_external":false
    },
    "secure_setting":{
        "enable_readonly_copy":false,
        "watermark":{
            "margin_type":2,
            "show_visitor_name":false,
            "show_text":false,
            "text":""
        },
        "enable_readonly_comment":false
    },
    "doc_member_list":[
        {
            "type":1,
            "userid":"USERID1",
            "auth":7
        },
        {
            "type":1,
            "tmp_external_userid":"TMP_EXTERNAL_USERID2",
            "auth":1
        }
    ],
    "co_auth_list":[
        {
            "type":2,
            "departmentid":1,
            "auth":1
        }
    ]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
access_rule	object	文档的查看规则
enable_corp_internal	bool	是否允许企业内成员浏览文档
corp_internal_auth	uint32	企业内成员主动查看文档后获得的权限类型 1:只读 2:读写（目前仅智能表可设置为读写）
enable_corp_external	bool	是否允许企业外成员浏览文档
corp_external_auth	uint32	企业内成员主动查看文档后获得的权限类型 1:只读 2:读写（目前仅智能表可设置为读写）
corp_internal_approve_only_by_admin	bool	企业内成员浏览文档是否必须由管理员审批，enable_corp_internal为false时，只能为true
corp_external_approve_only_by_admin	bool	企业外成员浏览文档是否必须由管理员审批，enable_corp_external和ban_share_external均为false时，该参数只能为true
ban_share_external	bool	是否允许企业外成员浏览文档
enable_readonly_copy	bool	仅浏览权限的成员是否允许导出、复制、打印
watermark	object	文档水印设置
margin_type	uint32	水印密度 1:稀疏 2:紧密
show_visitor_name	bool	是否展示访问者名字
show_text	bool	是否展示水印文字
text	bytes	水印文字
doc_member_list	obj[]	文档通知范围及权限列表
type	uint32	文档通知范围成员种类 1:user, 只支持成员
userid	bytes	企业成员的userid
tmp_external_userid	string	外部用户临时id。同一个用户在不同的文档中返回的该id不一致。
auth	uint32	该文档通知范围成员的权限 1:只读 2:读写（目前仅智能表可设置为读写） 7:管理员
co_auth_list	object	文档查看权限特定部门列表，可以直接浏览文档
type	uint32	特定部门列表 2:部门, 目前只支持部门
departmentid	uint64	特定部门id
auth	uint32	权限类型 1:只读,2:读写（目前仅智能表可设置为读写）

修改文档查看规则

最后更新：2024/08/21

该接口用于修改文档、表格、智能表格查看规则。

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/mod_doc_join_rule?access_token=ACCESS_TOKEN

请求包体

{
    "docid":"DOCID",
    "enable_corp_internal":true,
    "corp_internal_auth":1,
    "enable_corp_external":true,
    "corp_external_auth":1,
    "corp_internal_approve_only_by_admin":true,
    "corp_external_approve_only_by_admin":true,
    "ban_share_external":false,
    "update_co_auth_list":true,
    "co_auth_list":[
        {
            "departmentid":1,
            "auth":1,
            "type":2
        }
    ]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	操作的docid
enable_corp_internal	bool	否	是否允许企业内成员浏览文档, 有值则覆盖
corp_internal_auth	uint32	否	企业内成员主动查看文档后获得的权限类型 1:只读 2:读写（目前仅智能表可设置为读写）, 有值则覆盖
enable_corp_external	uint32	否	是否允许企业外成员浏览文档, 有值则覆盖
corp_external_auth	uint32	否	企业外成员主浏览文档后获得的权限类型 1:只读 2:读写（目前仅智能表可设置为读写）, 有值则覆盖
corp_internal_approve_only_by_admin	bool	否	企业内成员加入文档是否必须由管理员审批，enable_corp_internal为false时，只能为true，有值则覆盖。设置为true之前，文档需要有至少一个管理员。
corp_external_approve_only_by_admin	bool	否	企业外成员加入文档是否必须由管理员审批，enable_corp_external和ban_share_external均为false时，该参数只能为true，有值则覆盖。设置为true之前，文档需要有至少一个管理员。
ban_share_external	bool	否	是否禁止文档分享到企业外, 有值则覆盖
update_co_auth_list	bool	否	是否更新文档查看权限的特定部门, true时更新特定部门列表
co_auth_list	object[]	否	需要更新文档查看权限特定部门时, 覆盖之前部门, 特别的: 列表为空则清空
departmentid	uint64	否	文档查看权限特定部门id
auth	uint32	否	文档特定部门权限 1:只读 2:读写（目前仅智能表可设置为读写）
type	uint32	否	文档特定部门类型 2:部门, 目前只支持部门

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限
只能操作该应用创建的文档

返回示例

{
    "errcode": 0,
    "errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

修改文档通知范围及权限

最后更新：2024/05/30

该接口用于修改文档、表格、智能表格通知范围列表，可以新增文档、表格、智能表格通知范围并设置权限、修改已有范围的权限以及删除文档、表格、智能表格通知范围内的人员

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/mod_doc_member?access_token=ACCESS_TOKEN

请求包体

{
    "docid":"DOCID",
    "update_file_member_list":[
        {
            "type":1,
            "auth":7,
            "userid":"USERID1"
        }
     ],
    "del_file_member_list":[
        {
            "type":1,
            "userid":"USERID2"
        },
        {
            "type":1,
            "tmp_external_userid":"TMP_EXTERNAL_USERID2"
        }
   ]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	操作的文档id
update_file_member_list	obj[]	否	更新文档通知范围的列表, 批次大小最大100
type	uint32	是	文档通知范围的类型 1:用户。文档通知范围仅支持按人配置
auth	uint32	是	文档通知范围内人员获得的权限 1:只读权限 2:读写权限（目前仅智能表可设置为读写权限） 7:管理员权限，文档管理员最多三个
userid	string	否	企业内成员的ID
tmp_external_userid	string	否	外部用户临时id。同一个用户在不同的文档中返回的该id不一致。
del_file_member_list	obj[]	否	删除的文档通知范围列表，批次大小最大一百
type	uint32	是	文档通知范围的类型 1:用户。文档通知范围仅支持按人配置
userid	string	否	企业内成员的ID
tmp_external_userid	string	否	外部用户临时id。同一个用户在不同的文档中返回的该id不一致。

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限
只能操作该应用创建的文档

返回示例

{
    "errcode": 0,
    "errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

修改文档安全设置

最后更新：2024/05/30

该接口用于修改文档、表格、智能表格的安全设置

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/mod_doc_safty_setting?access_token=ACCESS_TOKEN

请求包体

{
    "docid":"DOCID",
    "enable_readonly_copy":false,
    "watermark":{
        "margin_type":1,
        "show_visitor_name":true,
        "show_text":true,
        "text":"test mark"
    }
}

参数说明

参数	类型	是否必须	说明
docid	string	是	操作的文档id
enable_readonly_copy	bool	否	是否允许只读成员复制、下载文档，有值则覆盖
watermark	object	否	水印设置
margin_type	uint32	否	水印疏密度，1:稀疏，2:紧密
show_visitor_name	bool	否	是否展示访问者名字水印，有值则覆盖
show_text	bool	否	是否展示文本水印，有值则覆盖
text	string	否	文字水印的文字，有值则覆盖

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限
只能操作该应用创建的文档

返回示例

{
    "errcode": 0,
    "errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

管理智能表格内容权限

最后更新：2024/11/21

智能表内容权限概述

智能表格可设置内容权限以详细配置文档成员对表格内容的操作权限。内容权限由全员权限以及至多20条成员额外权限组成。

权限明细

每条权限可以针对不同子表配置字段权限、记录权限、视图权限。

生效成员

对于全员权限，生效成员即是全部文档成员。对于成员额外权限，可以配置生效的成员范围。

查询智能表格子表权限

该接口用于查询智能表格子表权限详情

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/content_priv/get_sheet_priv?access_token=ACCESS_TOKEN

请求包体

{
	"docid": "DOCID",
	"type": 2,
	"rule_id_list": [
		"RULEID1", "RULEID2"
	]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	智能表ID，通过新建文档接口创建后获得
type	uint32	是	权限规则类型，1-全员权限，2-额外权限
rule_id_list	uint32 []	否	需要查询的规则id列表，查询额外权限时填写

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok",
	"rule_list": [{
		"rule_id": 1,
		"type": 1,
		"name": "全员权限",
		"priv_list": [{
				"sheet_id": "q979lj",
				"priv": 2,
				"can_insert_record": true,
				"can_delete_record": true,
				"record_priv": {
					"record_range_type": 1
				},
				"field_priv": {
					"field_range_type": 2,
					"field_rule_list": [{
						"field_id": "fsMGQS",
						"field_type": "FIELD_TYPE_TEXT",
						"can_edit": false,
						"can_insert": true,
						"can_view": true
					}],
					"field_default_rule": {
						"can_edit": false,
						"can_insert": false,
						"can_view": true
					}
				},
				"can_create_modify_delete_view": true
			},
			{
				"sheet_id": "kQ65QQ",
				"priv": 1
			}
		]
	}]
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
rule_list	object[]	权限列表
rule_list.type	uint32	权限规则类型，1-全员权限，2-额外权限。每个智能表格有且只有一个全员权限
rule_list.rule_id	uint32	当type为2时必填
rule_list.name	string	权限名称，仅当type为2时有效
rule_list.priv_list	object[]	针对不同子表设置内容权限
rule_list.priv_list.sheet_id	string	子表ID
rule_list.priv_list.priv	string	子表权限: 1-全部权限；2-可编辑；3-仅浏览；4-无权限
rule_list.priv_list.can_insert_record	bool	是否可以新增记录。仅当子表权限为`可编辑`时有意义
rule_list.priv_list.can_delete_record	bool	是否可以删除记录。仅当子表权限为`可编辑`时有意义
rule_list.priv_list.can_create_modify_delete_view	bool	是否可以增、删、改视图。
rule_list.priv_list.field_priv	object	按字段配置权限
rule_list.priv_list.field_priv.field_range_type	uint32	子表权限对所有字段生效还是部分字段生效：1-所有字段；2-部分字段。当值为2时可以配置各个字段独立的权限
rule_list.priv_list.field_priv.field_rule_list	object[]	按字段分别配置权限
rule_list.priv_list.field_priv.field_rule_list.field_id	string	字段id
priv_list.priv_list.field_priv.field_rule_list.field_type	string	字段类型，见FieldType
rule_list.priv_list.field_priv.field_rule_list.can_edit	bool	可编辑
rule_list.priv_list.field_priv.field_rule_list.can_insert	bool	可首次提交
rule_list.priv_list.field_priv.field_rule_list.can_view	bool	可查看
rule_list.priv_list.field_priv.field_default_rule	object	field_rule_list里未指定字段和后续新增字段的默认配置，与field_rule_list一样可指定can_edit/can_insert/can_view三个权限
rule_list.priv_list.record_priv	object	按记录配置权限，priv=2或3时必填
rule_list.priv_list.record_priv.record_range_type	uint32	子表权限对记录生效范围：1-全部记录；2-满足任意条件的记录；3-满足全部条件的记录
rule_list.priv_list.record_priv.record_rule_list	object[]	记录的条件列表，当record_range_type为2或3时生效
rule_list.priv_list.record_priv.record_rule_list.field_id	string	字段id，只有人员、单选、多选三种类型的字段有效。当field_id为`CREATED_USER`时表示记录创建者
rule_list.priv_list.record_priv.record_rule_list.field_type	string	是字段类型，见FieldType
rule_list.priv_list.record_priv.record_rule_list.oper_type	uint32	逻辑判断类型：1-包含自己（人员字段）；2-包含value；3-不包含value；4-等于value；5-不等于value；6-为空；7-非空；
rule_list.priv_list.record_priv.record_rule_list.value	string[]	用于单选、多选字段的option_id
rule_list.priv_list.record_priv.other_priv	uint32	当记录不满足条件的时的权限类型：1-不可编辑 2-不可查看
rule_list.priv_list.clear	bool	清除子表的设置，恢复默认权限

更新智能表格子表权限

该接口用于设置全员权限或者成员额外权限的权限详情

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/content_priv/update_sheet_priv?access_token=ACCESS_TOKEN

请求包体

{
	"docid": "DOCID",
	"type": 2,
	"rule_id": 2,
	"name": "NAME",
	"priv_list": [{
		"sheet_id": "SHEETID",
		"priv": 1,
		"can_insert_record": true,
		"can_delete_record": true,
		"can_create_modify_delete_view": true,
		"field_priv": {
			"field_range_type": 2,
			"field_rule_list": [{
					"field_id": "FIELDID1",
					"can_edit": true,
					"can_insert": true,
					"can_view": true
				},
				{
					"field_id": "FIELDID2",
					"can_edit": false,
					"can_insert": true,
					"can_view": true
				}
			]
		},
		"record_priv": {
			"record_range_type": 2,
			"record_rule_list": [{
					"field_id": "FIELDI1",
					"field_type": "FIELD_TYPE_TEXT",
					"oper_type": 1
				},
				{
					"field_id": "CREATED_USER",
					"oper_type": 1
				},
				{
					"field_id": "FIELDID2",
					"oper_type": 2,
					"field_type": "FIELD_TYPE_SELECT",
					"value": [
						"OPTION1", "OPTION2", "OPTION3"
					]
				}
			]
		},
		"clear": false
	}]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	智能表ID，通过新建文档接口创建后获得
type	uint32	是	权限规则类型，1-全员权限，2-额外权限。每个智能表格有且只有一个全员权限
rule_id	uint32	否	当type为2时必填
name	string	否	更新权限名称，仅当type为2时有效
priv_list	object[]	否	针对不同子表设置内容权限
priv_list.sheet_id	string	是	子表ID
priv_list.priv	string	是	子表权限: 1-全部权限；2-可编辑；3-仅浏览；4-无权限
priv_list.can_insert_record	bool	否	是否可以新增记录。仅当子表权限为`可编辑`时有意义
priv_list.can_delete_record	bool	否	是否可以删除记录。仅当子表权限为`可编辑`时有意义
priv_list.can_create_modify_delete_view	bool	否	是否可以增、删、改视图。
priv_list.field_priv	object	否	按字段配置权限
priv_list.field_priv.field_range_type	uint32	是	子表权限对所有字段生效还是部分字段生效：1-所有字段；2-部分字段。当值为2时可以配置各个字段独立的权限
priv_list.field_priv.field_rule_list	object[]	是	按字段分别配置权限
priv_list.field_priv.field_rule_list.field_id	string	是	字段id
priv_list.field_priv.field_rule_list.field_type	string	是	字段类型，见FieldType
priv_list.field_priv.field_rule_list.can_edit	bool	是	可编辑
priv_list.field_priv.field_rule_list.can_insert	bool	是	可首次提交
priv_list.field_priv.field_rule_list.can_view	bool	是	可查看
priv_list.field_priv.field_default_rule	object	否	field_rule_list里未指定字段和后续新增字段的默认配置，与field_rule_list一样可指定can_edit/can_insert/can_view三个权限。type为1时必填，type为2时不可指定field_default_rule
priv_list.record_priv	object	否	按记录配置权限，priv=2或3时必填
priv_list.record_priv.record_range_type	uint32	是	子表权限对记录生效范围：1-全部记录；2-满足任意条件的记录；3-满足全部条件的记录
priv_list.record_priv.record_rule_list	object[]	否	记录的条件列表，当record_range_type为2或3时生效
priv_list.record_priv.record_rule_list.field_id	string	是	字段id，只有人员、单选、多选三种类型的字段有效。当field_id为`CREATED_USER`时表示记录创建者
priv_list.record_priv.record_rule_list.field_type	string	否	字段类型FieldType，当field_id为`CREATED_USER`时不填此字段，其他类型必填
priv_list.record_priv.record_rule_list.oper_type	uint32	是	逻辑判断类型：1-包含自己（人员字段）；2-包含value；3-不包含value；4-等于value；5-不等于value；6-为空；7-非空；
priv_list.record_priv.record_rule_list.value	string[]	是	用于单选、多选字段的option_id
priv_list.record_priv.other_priv	uint32	是	当记录不满足条件的时的权限类型：1-不可编辑 2-不可查看
priv_list.clear	bool	否	清除子表的设置，恢复默认权限

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
	"errcode": 0,
	"errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

新增智能表格指定成员额外权限

该接口用于新增智能表格指定成员额外权限

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/content_priv/create_rule?access_token=ACCESS_TOKEN

请求包体

{
	"docid": "DOCID",
	"name": "NAME"
}

参数说明

参数	类型	是否必须	说明
docid	string	是	智能表ID，通过新建文档接口创建后获得
name	string	是	权限规则名称，不可重复

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "rule_id": 1
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明
rule_id	uint32	成员权限规则id

更新智能表格指定成员额外权限

该接口用于更新智能表格指定成员额外权限，成员最多可设置50个

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/content_priv/mod_rule_member?access_token=ACCESS_TOKEN

请求包体

{
	"docid": "DOCID",
	"rule_id": 3,
	"add_member_range": {
		"userid_list": [
			"userid1"
		]
	},
	"del_member_range": {
		"userid_list": [
			"userid2"
		]
	}
}

参数说明

参数	类型	是否必须	说明
docid	string	是	智能表ID，通过新建文档接口创建后获得
rule_id	uint32	是	需要更新的id
add_member_range	object	否	新增成员
add_member_range.userid_list	string []	否	新增成员的userid
del_member_range	object	否	删除成员
del_member_range.userid_list	string []	否	删除成员的userid

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

删除智能表格指定成员额外权限

该接口用于删除智能表格指定成员额外权限

请求方式：POST（HTTPS） 请求地址: https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/content_priv/delete_rule?access_token=ACCESS_TOKEN

请求包体

{
	"docid": "DOCID",
	"rule_id_list": [
		2
	]
}

参数说明

参数	类型	是否必须	说明
docid	string	是	智能表ID，通过新建文档接口创建后获得
rule_id_list	uint32 []	是	需要删除的规则id列表

权限说明

自建应用需配置到“可调用应用”列表中的应用secret所获取的accesstoken来调用（accesstoken如何获取？）
第三方应用需具有“文档”权限
代开发自建应用需具有“文档”权限

返回示例

{
    "errcode": 0,
    "errmsg": "ok"
}

参数说明

参数	类型	说明
errcode	int32	错误码
errmsg	string	错误码说明

190 KiB Raw Blame History Unescape Escape

概述

接口创建文档表现

接口创建智能表格的表现

配置可调用文档接口的应用

频率控制

#对文件操作的频率控制约定

#对于文档操作的频率控制约定

获取access_token

获取企业微信接口IP段

管理文档

新建文档

重命名文档

删除文档

获取文档基础信息

分享文档

管理智能表格内容

添加子表

删除子表

更新子表

查询子表

添加视图

参数详细说明

View

ViewType

GanttViewProperty

CalendarViewProperty

删除视图

参数详细说明

View

ViewProperty

SortSpec

GroupSpec

FilterSpec

Condition

Operator

FilterDataTimeValue

DateTimeType

ViewColorConfig

ViewColorCondition

ViewColorConditionType

ViewColor

查询视图

参数详细说明

View

ViewType

ViewProperty

SortSpec

GroupSpec

FilterSpec

Condition

FieldType

Operator

FilterDataTimeValue

DateTimeType

ViewColorConfig

ViewColorCondition

ViewColorConditionType

ViewColor

添加字段

参数详细说明

AddField

FieldType

NumberFieldProperty

CheckboxFieldProperty

DateTimeFieldProperty

AttachmentFieldProperty

UserFieldProperty

UrlFieldProperty

SelectFieldProperty

CreatedTimeFieldProperty

ModifiedTimeFieldProperty

ProgressFieldProperty

SingleSelectFieldProperty

ReferenceFieldProperty

LocationFieldProperty

LocationFieldProperty

AutoNumberFieldProperty

CurrencyFieldProperty

WwGroupFieldProperty

190 KiB

Raw Blame History