linzelong/G41_TAPD_BUG_SYNC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
G41_TAPD_BUG_SYNC/智能表格接口文档.md

193 KiB
Raw Permalink Blame History

概述

最后更新：2025/07/16

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

提示

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

接口创建文档表现

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

接口创建智能表格的表现

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

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

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

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

频率控制

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

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

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

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

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

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

频控标签为：

openID

300

对于导入接口：

openID

60

对于导出接口：

维度 限制频率（次 / 天）
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

字段信息：

img注意

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

参数名 类型 是否必填 描述
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 错误码说明

更新字段

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

img注意

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

请求方式：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

字段信息：

img注意

字段属性与字段类型是匹配的，一种字段类型对应一种字段属性 更新时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

字段信息：

img注意

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

参数名 类型 描述
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条成员额外权限组成。

权限明细

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

生效成员

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

修改文档成员与权限

最后更新：2026/03/12

该接口用于管理文档、表格、智能表格的文档成员，支持增加或删除成员、修改成员的权限。

请求方式：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"
}

查询智能表格子表权限

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

请求方式：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 错误码说明