腾讯文档开放API
API 概览
文档相关接口名称 | 接口功能 |
/openapi/v1/doc/create | 创建文档 |
/openapi/v1/doc/delete | 删除自己创建文档 |
/openapi/v1/doc/rename | 修改文档标题 |
/openapi/v1/doc/query | 查询文档信息 |
/openapi/v1/doc/import | 导入文档 |
/openapi/v1/doc/export | 导出文档,权限需要单独申请 |
/openapi/v1/doc/trans | 文档转让 |
/openapi/v1/doc/copy | 生成副本 |
/openapi/v1/doc/list | 查询文档列表 |
/openapi/v1/doc/list_created | 增量拉取我创建的文档列表 |
/openapi/v1/doc/list_browse | 增量拉取我浏览的文档列表 |
登录相关接口名称 | 接口功能 |
/openapi/v1/user/auth | 获取用户登录态 |
权限相关接口名称 | 接口功能 |
/openapi/v1/privilege/set | 设置文档权限 |
/openapi/v1/privilege/get | 获取文档权限 |
打开文档相关接口名称 | 接口功能 |
/openapi/v1/jump/open | 打开文档 |
开发者与应用注册
开发者需要先到官网API接口(https://docs.qq.com/open-api.html)“立即申请”登记信息,后续将会有商务线
1.调用步骤
1.1 术语解释
- 第三方平台:指使用腾讯文档开放API的第三方开发者
- 文档ID:字符串,用来标识文档的唯一ID
- 文档类型:数字,0:Word,1:Excel,2:Form
1.2 获取用户登录态
说明:
- 为保证安全性,获取登录态的过程中需要回调第三方平台查询用户信息
- 由于本步骤中尚未获取到用户登录态,所以 1.2 调用 auth 接口 和 1.3 查询用户信息接口需要对接口进行签名,具体的签名算法见 【接口鉴权】
- 1.2 接口名称为 /openapi/v1/user/auth
- 1.3 第三方需提供查询用户信息 get_third_userinfo
- 1.5 返回 toid,toid_key(加密的A2)
1.3 调用API接口
以 创建文档接口(/openapi/v1/doc/create)为例
2.请求方式
- 通信协议:HTTPS
- 接口地址:
- 请求的HOST:第三方申请到的独立域名,例如:example.txdocs.qq.com。如果不申请使用独立域名,则使用此通用域名:tob.txdocs.qq.com。
- 请求方式:独立域名---https://example.txdocs.qq.com/{接口名} (示例)
通用域名---https://tob.txdocs.qq.com/{接口名}
- 请求方法:支持 POST 和 GET 请求。
- POST 请求目前仅支持 Content-Type 类型为 application/x-www-form-urlencoded
- 字符编码:均使用UTF-8编码
3.公共参数
公共参数是用于标识用户和接口鉴权目的的参数,如非必要,在每个接口单独的接口文档中不再对这些参数进行说明,但每次请求均需要携带这些参数,才能正常发起请求。
为避免接口参数冲突,公共参数的参数名为全大写字母。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 应用注册成功后获取 |
TIMESTAMP | Integer | 是 | 当前 UINX 时间戳,即发起 API 请求的时间,如果时间与当前时间相差过大,会引起签名过期错误 |
NONCE | Integer | 是 | 随机正整数,用于防止重放攻击,短时间内 Nonce 不能重复 |
SIGNATURE | String | 是 | 请求签名,用来验证此次请求的合法性,具体计算方法见【接口鉴权】 |
TOID | String | 否 | 用户ID |
TOID_KEY | String | 否 | 用户登录态 |
4.接口鉴权
获取登录态时需要对接口进行签名,腾讯文档开放平台在调用第三方接口时,第三方平台也需要对请求进行签名校验已确保请求来源合法。
以 登录接口(/openapi/v1/user/auth) 为例,发送的请求参数如下:
参数名称 | 类型 | 参数值 | 描述 |
APPID | Integer | 1001 | 应用的 APPID |
TIMESTAMP | Integer | 1465185768 | 当前 UINX 时间戳 |
NONCE | Integer | 4529053332324 | 随机正整数 |
third_token | String | xxxxx | 第三方用户 token |
注意:这里只是例子,用于说明接口签名的过程,实际接口参数可能与此不同
4.1 对参数排序
首先对所有请求参数按参数名的字典序( ASCII 码)升序排序
注意:
1)只按参数名进行排序,参数值保持对应即可,不参与比大小;
2)按 ASCII 码比大小,如 InstanceIds.2 要排在 InstanceIds.12 后面,不是按字母表,也不是按数值。
用户可以借助编程语言中的相关排序函数来实现这一功能,如 php 中的 ksort 函数。
上述示例参数的排序结果如下:
'APPID' : 1001 'NONCE' : 4529053332324, 'TIMESTAMP' : 1465185768, 'third_token':xxxxx |
4.2 拼接请求字符串
此步骤生成请求字符串。 将把上一步排序好的请求参数格式化成“参数名称”=“参数值”的形式
注意:“参数名称“和“参数值”为原始值而非url编码后的值。
然后将格式化后的各个参数用"&"拼接在一起。
最终生成的请求字符串为:
APPID=1001&NONCE=4529053332324&TIMESTAMP=1465185768&third_token=xxxxx |
4.1.3 拼接签名原文字符串
此步骤生成签名原文字符串。 签名原文字符串由以下几个参数构成:
- 请求方法: 支持 POST 和 GET 方式,这里使用 GET 请求,注意方法为全大写。
- 请求主机: 根据实际请求的域名填写
- 例如:example.txdocs.qq.com
- 请求路径: 即接口名称
- 请求字符串: 即上一步生成的请求字符串
签名原文串的拼接规则为:
请求方法 + 请求域名 +请求路径 + ? + 请求字符串
示例的拼接结果为:
GETexample.txdocs.qq.com/openapi/v1/auth?APPID=1001&NONCE=4529053332324&TIMESTAMP=1465185768&third_token=xxxxx |
4.3 生成签名串
此步骤生成签名串。 首先使用 HMAC-SHA1 算法对上一步中获得的签名原文字符串进行签名,然后将生成的签名串使用 Base64 进行编码,即可获得最终的签名串。
具体代码如下,以 PHP 语言为例:
$appkey = 'fakeAppkey'; $srcStr = 'GETexample.txdocs.qq.com/openapi/v1/auth?APPID=1001&NONCE=4529053332324&TIMESTAMP=1465185768&third_token=xxxxx'; $signStr = base64_encode(hash_hmac('sha1', $srcStr, $appkey, true)); echo $signStr; |
最终得到的签名串为:
Lrj7E+bzqHA4zKnnBENruUnuUQk= |
使用其它程序设计语言开发时,可用上面示例中的原文进行签名验证,得到的签名串与例子中的一致即可。
4.4 签名串编码
生成的签名串并不能直接作为请求参数,需要对其进行 URL 编码。
注意:如果用户的请求方法是 GET,或者请求方法为 POST 同时 Content-Type 为 application/x-www-form-urlencoded ,则对所有请求参数值均需要做 URL 编码。
非 ASCII 字符在 URL 编码前需要先以 UTF-8 进行编码。
如上一步生成的签名串为:
Lrj7E+bzqHA4zKnnBENruUnuUQk= |
经过 urlencode 之后,最终得到的签名串请求参数(SIGNTURE)为:
Lrj7E%2BbzqHA4zKnnBENruUnuUQk%3D |
注意:有些编程语言的 http 库会自动为所有参数进行 urlencode ,在这种情况下,就不需要对签名串进行 URL 编码了,否则两次 URL 编码会导致签名失败。
5.错误码
5.1 网关返回的错误码
错误代码 | 错误描述 |
1000 | API网关:内部错误 |
1001 | API网关:TOID_KEY 错误 |
1002 | API网关:逻辑错误 |
1003 | API网关:网络错误 |
1004 | API网关:参数错误 |
1005 | API网关:获取应用信息失败 |
1006 | API网关:应用状态错误 |
1007 | API网关:签名错误 |
1008-2000 | API网关:预留 |
5.1 CGI返回的错误码(部分)
错误代码 | 错误描述 |
1001 | 登录无效 |
10000 | 无APPID |
10001 | 无TOID信息 |
10002 | 无第三方token信息 |
10003 | 登录失败 |
10004 | 登录签名为空 |
10005 | 用户信息拉取失败 |
10006 | 用户信息APPID与第三方APPID不匹配 |
10007 | APPKey不存在 |
10008 | APP信息拉取失败 |
10009 | JUMPCODE为空 |
10010 | JUMPCODE读取失败 |
API接口详情
下述接口示例中均以example.txdocs.qq.com为HOST来进行举例,实际请求时请使用申请到的第三方独立域名,无独立域名则使用通用域名tob.txdocs.qq.com。
另外,如果用户的请求方法是 GET,或者请求方法为 POST 同时 Content-Type 为 application/x-www-form-urlencoded ,则对所有请求参数值均需要做 URL 编码。(若出现签名错误、参数错误等提示,请检查是否有正确地URL编码)
1.登录相关接口
1.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/user/auth |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用于获取用户的登录态
注意:此接口需要签名验证
1.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 公共参数 |
TIMESTAMP | Integer | 是 | 公共参数 |
NONCE | Integer | 是 | 公共参数 |
SIGNATURE | String | 是 | 公共参数 |
下面登录方式三选一,每次只能传一种方式
企业微信 Token/Code 登录时,传下列参数
参数名称 | 类型 | 必选 | 描述 |
third_token | String | 是 | 第三方票据,用户向第三方验证用户信息 |
login_type | Integer | 是 | 填 0 |
QQ 登录时,传下列参数
参数名称 | 类型 | 必选 | 描述 |
third_daid | Integer | 是 | 第三方登录域 |
third_puin | Integer | 是 | 第三方登录QQ号 |
third_pskey | String | 是 | 第三方登录PSkey |
login_type | Integer | 是 | 填 1 |
微信登录时,传下列参数
参数名称 | 类型 | 必选 | 描述 |
third_wx_appid | String | 是 | 第三方微信appid |
third_openid | String | 是 | 第三方微信登录OpenID |
third_access_token | String | 是 | 第三方微信access token |
login_type | Integer | 是 | 填 2 |
第三方回调登录时,传下列参数
参数名称 | 类型 | 必选 | 描述 |
third_token | String | 是 | 第三方票据,用户向第三方验证用户信息 |
login_type | Integer | 是 | 填 3 |
1.3 输出参数
参数名称 | 类型 | 描述 |
toid | String | 用户ID |
toid_key | String | 用户登录key |
jump_code | String | 跳转用一次性 code |
若是采用第三方回调登录的方式,如果登录时回调第三方提供的用户信息回调服务出错,则此登录接口会返回错误:{“cgicode”:10003, "ret":43810, "msg":"0x16184 response error, msg=third toid serv error}
1.4 示例
输入示例:
https://example.txdocs.qq.com/openapi/v1/user/auth?third_token=1001 |
输出示例:
{ "ret": 0, "msg": "ok", "data": { "toid": "144115210451427855", "toid_key": "L8HfmGLnqHHie%252FYLT6f%252BOqivGW9WusoWWRkCvTwqANPqp8zj", "jump_code": "4c0015fec4e0cfad148858dabdd985ca4ac5d8a02a2db87816f51575ce7b2369" } } |
2.文档相关接口
2.1 创建文档
2.1.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/create |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来创建文档。若要打开文档,请使用/openapi/v1/jump/open接口(4.1)。
2.1.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
title | String | 是 | 文档标题 |
doc_type | Int | 是 | 文档类型 0=文档 1=表格 2=收集表 |
disable_auto_rename | Int | 否 | 是否禁止自动修改标题能力,1为禁止 |
2.1.3. 输出参数
参数名称 | 类型 | 描述 |
doc_id | String | 文档ID,此ID用在后面各种文档操作接口 |
doc_url | String | 文档地址 |
2.1.4. 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/create title=name&doc_type=1 |
输出示例:
{ "ret": 0, "msg": "ok", "data": { "doc_id": "DY0dLUHNZWFVFTXdt", "doc_url": "//docs.qq.com/doc/DV3Jic1Z1Y0FxcE1J?appid=101520907&od_appid=101520907" } } |
2.2 删除文档
2.2.1 接口描述
描述 | 定义 |
接口名 | /openap/v1/doc/delete |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来删除文档,此接口会校验toid是否是该文档的拥有者(拥有者并非一定是创建者,因为拥有者可以转让,参考 /openapi/v1/doc/trans)
2.2.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
doc_id | String | 是 | 文档ID,创建文档后获得 |
2.2.3 输出参数
无
2.2.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/delete doc_id=xx |
输出示例:
{ "ret": 0, "msg": "ok" } |
2.3 还原文档
2.3.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/recover |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来还原文档,此接口会校验toid是否是该文档的拥有者(拥有者并非一定是创建者,因为拥有者可以转让,参考 /openapi/v1/doc/trans)
2.3.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
doc_id | String | 是 | 文档ID,创建文档后获得 |
2.3.3 输出参数
无
2.3.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/recover doc_id=xx |
输出示例:
{ "ret": 0, "msg": "ok" } |
2.4 修改文档标题
2.4.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/rename |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来修改文档标题,此接口会校验当前toid是否有文档的编辑权限。
2.4.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
doc_id | String | 是 | 文档ID,创建文档后获得 |
title | String | 是 | 文档修改之后的标题 |
2.4.3 输出参数
无
2.4.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/rename doc_id=xx&name=xxxx |
输出示例:
{ "ret": 0, "msg": "ok" } |
2.5 查询文档信息
2.5.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/query |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来查询文档信息
2.5.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
doc_id[] | Array | 是 | 文档ID列表 |
2.5.3 输出参数
参数名称 | 类型 | 描述 |
doc_id | String | 文档id |
title | String | 文档标题 |
is_creator | Int | 是否为文档创建者 |
doc_type | Int | 文档类型 |
doc_status | Int | 0; // 状态正常 1; // 已删除 2; // 在回收站中 3; // 父文件夹在回收站中 |
doc_url | String | 文档地址 |
2.5.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/query doc_id[0]=xx&doc_id[1]=bb |
输出示例:
{ "ret": 0, "msg": "ok", "data": { "doc_info": [ { "doc_id": "aaa$bbb", "title": "文档相关接口", "is_creator": 0, "doc_type": 1, "doc_url": "//docs.qq.com/doc/DV3Jic1Z1Y0FxcE1J?appid=101520907&od_appid=101520907" }, { "doc_id": "bbb$ccc", "title": "文档相关接口", "is_creator": 0, "doc_type": 1, "doc_url": "//docs.qq.com/doc/DV3Jic1Z1Y0FxcE1J?appid=101520907&od_appid=101520907" } ] } } |
2.5 导入上传文档
2.5.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/import |
请求方式 | POST |
请求格式 | multipart/form-data |
本接口用来导入文档,导入文档大小限制20M。
2.5.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
file | File | 是 | 文档数据 |
2.5.3 输出参数
参数名称 | 类型 | 描述 |
doc_id | string | 文档doc_id 为 {domainId}${localPadId} |
title | string | 文档标题 |
padType | string | 文档类型: doc | sheet | slide |
2.5.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/import ------WebKitFormBoundary7Iba3ikiiHUdj9Km Content-Disposition: form-data; name="APPID" xxx ------WebKitFormBoundary7Iba3ikiiHUdj9Km Content-Disposition: form-data; name="TOID" xxx ------WebKitFormBoundary7Iba3ikiiHUdj9Km Content-Disposition: form-data; name="TOID_KEY" xxxxxx ------WebKitFormBoundary7Iba3ikiiHUdj9Km Content-Disposition: form-data; name="file"; filename="eeeeeeeeeeeee.docx" Content-Type: application/kswps 【fileData】 ------WebKitFormBoundary7Iba3ikiiHUdj9Km-- |
输出示例:
{ "ret": 0, "title": "测试文档", “padType”: "doc", "domainId":"300000000", "localPadId":"MyhkOqWXZCWR" } |
2.6 文档拥有者转让
2.6.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/trans |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来转让文档
2.6.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
doc_id | String | 是 | 文档 Id |
to_toid | Integer | 是 | 转让目标用户TOID |
2.6.3 输出参数
无
2.6.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/trans doc_id=xx&to_toid=111111111 |
输出示例:
{ "ret": 0, "msg": "ok" } |
2.7 生成副本
2.7.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/copy |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来生成副本
2.7.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
doc_id | String | 是 | 文档的doc_id |
doc_type | Int | 是 | 文档类型 |
title | String | 是 | 文档标题 |
2.7.3 输出参数
参数名称 | 类型 | 描述 |
doc_id | string | 新的文档doc_id |
2.7.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/copy doc_id=xx$aaa&title=xxxx&doc_type=1 |
输出示例:
{ "ret": 0, "msg": "ok", "data": { "doc_id": "3000000$aaaa", } } |
2.8 增量拉取(我创建的)文档列表
2.8.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/list_created |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来查询文档信息
2.8.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
start | Int | 是 | 上次拉取列表的Next值或者上次请求时间 |
limit | Int | 是 | 最多拉取数,最大20 |
fetch_type | Int | 是 | 0 按最后修改时间降序,以分页的方式拉取,start传起始个数,limit传每次拉取的个数,返回next为下次拉取需要传递的start 2 按最后修改时间升序,以时间范围的方式拉取,start传其实时间戳,limit传每次拉取个数,返回next为下次拉取需要传递的start,如果传0,拉取最旧的 3 按seq升序,逻辑同2一样,不传时间戳,传seq,使用返回的next定位 |
2.8.3 输出参数
参数名称 | 类型 | 描述 |
list | Array | 文档列表 |
next | Int | 下次拉取行数,0为结束 |
list.Index.doc_id | String | 文档Id |
list.Index.title | String | 创建标题 |
list.Index.doc_type | Int | 文档类型 |
list.Index.is_creator | Int | 是否文档创建者 |
list.Index.last_modify_ts | Int | 最后修改时间 |
list.Index.create_ts | Int | 创建时间 |
list.Index.order_ts | Int | 排序用时间 |
list.Index.last_modify_third_uid | String | 最后修改人(第三方平台上的uid) |
list.Index.doc_status | Int | 0; // 状态正常 1; // 已删除 2; // 在回收站中 3; // 父文件夹在回收站中 |
list.Index.last_modify_nick | String | 最后修改人昵称 |
list.Index.owner_third_uid | String | 创建者(第三方平台上的uid) |
list.Index.last_modify_seq | Int | Seq 数 |
2.8.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/list_created |
输出示例:
{ "ret": 0, "msg": "ok", "data" : { "next": 20, "list": { [{ "doc_id": "AA$AA", "title": "title", "doc_type": 0, "is_creator": 1, "last_modify_ts": 1528880357, "create_ts": 1528880357, "last_modify_third_uid": "aaa", "doc_status": 0, "order_ts":111, "last_modify_nick": "111" }] } } } |
2.9 增量拉取(我浏览的)文档列表
2.9.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/list_browse |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来查询文档信息
2.9.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
start | Int | 是 | 拉取起始时间,第一次填0,后续填next |
limit | Int | 是 | 最多拉取数,最大20 |
fetch_type | Int | 是 | 0 按时间降序 2 按时间升序 3 为seq升序 |
2.9.3 输出参数
参数名称 | 类型 | 描述 |
list | Array | 文档列表 |
list.Index.doc_id | String | 文档Id |
list.Index.title | String | 创建标题 |
list.Index.doc_type | Int | 文档类型 |
list.Index.is_creator | Int | 是否文档创建者 |
list.Index.last_modify_ts | Int | 最后修改时间 |
list.Index.create_ts | Int | 创建时间 |
list.Index.order_ts | Int | 排序用时间 |
list.Index.last_modify_third_uid | String | 最后修改人(第三方平台上的uid) |
list.Index.list_item_status | Int | 0; // 状态正常 1; // 已删除 2; // 在回收站中 3; // 父文件夹在回收站中 |
list.Index.last_modify_nick | String | 最后修改人昵称 |
list.Index.owner_third_uid | String | 创建者(第三方平台上的uid) |
list.Index.last_modify_seq | Int | Seq 数 |
next | Int | 下次拉取行数,0为结束 |
2.9.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/list_browse |
输出示例:
{ "ret": 0, "msg": "ok", "data" : "list": { [{ "doc_id": "AA$AA", "title": "title", "doc_type": 0, "is_creator": 1, "last_modify_ts": 1528880357, "create_ts": 1528880357, "last_modify_third_uid": "aaa", "list_item_status": 0, "order_ts":111, "last_modify_nick": "111" }] } } } |
2.10 导出接口
2.10.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/export |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口是提供给开放平台调用导出接口
2.10.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
doc_id | string | 是 | doc_id |
2.10.3 输出参数
参数名称 | 类型 | 描述 |
doc_id | string | doc_id |
file_size | int | 导出文件大小 |
doc_type | int | 文档类型 |
download_url | string | 导出文件下载地址 |
cookie_name | string | cookie名 |
cookie_value | string | cookie值 |
2.10.4 示例
输入示例:
POST https://docs.qq.com/openapi/v1/doc/export doc_id=300000$fnUbfJmUIawz |
输出示例:
{ "ret": 0, "msg": "ok", "data":{ "doc_id": "300000$fnUbfJmUIawz", "file_size": 524288, "doc_type": 0, "download_url":"https://docs.qq.com/ep/pad/exportdata_open?s=286d81d182ac0dabb78a48df8da132fe", "cookie_name":"tdefd", "cookie_value":"3678d6dd" } } |
2.11 设置水印接口
2.11.1 接口描述
描述 | 定义 |
接口名 | /dop-api/setmark |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用于给腾讯文档设置水印
2.11.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
padId | string | 是 | 腾讯文档id |
mark | string | 是 | 水印信息,json字符串,具体格式如下: { "type":"xxx", //水印类型,text:文字水印。目前就只有文字水 //印类型。 "text":"xxx", //水印所展示的文字 "marginType":x, //1:宽松型,2:紧密型 "selfHide":x, //0:对自己不隐藏,1:对自己隐藏 "s":{"private":x} //访客水印, private取值1表示设置访客水印 //prievate取值0表示未设置访客水印.设置了访 //客水印后,水印展示的是访客昵称。 } |
2.11.3 输出参数
参数名称 | 类型 | 描述 |
retcode | int | 返回码,0表示成功,非0表示失败 |
2.11.4 示例
输入示例:
POST https://docs.qq.com/dop-api/setmark padid=300000000$LxjWEpdWtVQK&mark={"type":"text","text":"waha","marginType":2,"selfHide":0,"s":{"private":0}} |
输出示例:
{ "retcode": 0 } |
2.12 预览导入文档
2.12.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/preview_import_office |
请求方式 | POST |
请求格式 | multipart/form-data |
本接口用来预览导入文档
2.12.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
file | File | 是 | 文档数据 |
2.11.3 输出参数
参数名称 | 类型 | 描述 |
doc_id | string | 文档doc_id 为 {domainId}${localPadId} |
doc_type | int | 文档类型 |
preview_key | string | 预览key,调用preview_save_mylist的时候使用 |
2.11.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/preview_import_office ------WebKitFormBoundary7Iba3ikiiHUdj9Km Content-Disposition: form-data; name="APPID" xxx ------WebKitFormBoundary7Iba3ikiiHUdj9Km Content-Disposition: form-data; name="TOID" xxx ------WebKitFormBoundary7Iba3ikiiHUdj9Km Content-Disposition: form-data; name="TOID_KEY" xxxxxx ------WebKitFormBoundary7Iba3ikiiHUdj9Km Content-Disposition: form-data; name="file"; filename="eeeeeeeeeeeee.docx" Content-Type: application/kswps 【fileData】 ------WebKitFormBoundary7Iba3ikiiHUdj9Km-- |
输出示例:
{ "ret": 0, "msg": "ok", "data":{ "doc_id": "300000$fnUbfJmUIawz", "doc_type" : 0, "preview_key":"f957cd0c687edd96b7c8d3f762fd69e4" } } |
2.12 保存预览导入文件
2.12.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/preview_save_mylist |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来保存预览导入文档
2.12.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
preview_key | String | 是 | 预览导入接口返回的preview_key |
2.12.3 输出参数
参数名称 | 类型 | 描述 |
doc_id | string | 文档doc_id 为 {domainId}${localPadId} |
2.12.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/preview_save_mylist preview_key=f957cd0c687edd96b7c8d3f762fd69e4&APPID=xxx&TOID=xxx&TOID_KEY=xxx |
输出示例:
{ "ret": 0, "msg": "ok", "data":{ "doc_id": "300000$fnUbfJmUIawz" } } |
2.13 彻底删除文档
2.13.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/burn |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来彻底删除文档,文档将直接删除,不可恢复,此接口会校验toid是否是该文档的拥有者(拥有者并非一定是创建者,因为拥有者可以转让,参考 /openapi/v1/doc/trans)
2.13.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
doc_id | String | 是 | 文档ID,创建文档后获得 |
2.13.3 输出参数
参数名称 | 类型 | 描述 |
无 |
2.14.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/burn doc_id=xx |
输出示例:
{ "ret": 0, "msg": "ok" } |
2.14 分片上传预上传文档
2.14.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/multipart/preupload |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来预上传一个本地文档
2.14.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 参数位置 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 | |
TOID | String | 是 | 用户ID,登录后获得 | |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 | |
file_name | String | multipart/form-data json | 是 | 文件名(test.pdf) |
file_size | Uint64 | multipart/form-data json | 是 | 文件大小 |
block_size | Uint64 | multipart/form-data json | 是 | 分片大小(目前后台限制在512KB的倍数,最大为4MB,后台会检查);当上传小于4MB文件并期望整个文件一次性上传,此时,block_size填0即可;若该文件需要存储到cos(例如pdf),则分片大小至少为1MB(当文件大于1MB时) |
channel_count | Uint64 | multipart/form-data json | 是 | 终端期待使用的通道数量(最多8通道) |
file_md5 | String | multipart/form-data json | 是 | 文件md5(HEX) |
data | byte[] | multipart/form-data 二进制 | 否 | 文件数据(可选) |
2.14.3 输出参数
参数名称 | 类型 | 描述 |
ret | int | 返回码 |
msg | string | 错误描述 |
upload_key | string | 上传文件的唯一标识,此后所有DocUploadPiece请求都需要带上该字段 |
upload_state | int | 上传状态 1:UploadNextPacket,需要上传下一分片; 2:UploadFinished,上传文件完成; 3:WaitOtherFinish,使用多个通道才会返回,表明当前通道已经上传完所有分片,需要等待其他通道上传完成 |
channel_list | JSON Array | 通道信息(包含该通道分片上传信息),{"id":uint32 channelid,"offset":uint64 offset,"len":uint64 len} |
channel_count | int | 后台实际分配给前端使用的通道数量(最多8通道,通道数量*分片大小小于等于文件大小,前端使用的实际物理连接数需小于等于通道数) |
uploaded_data_len | uint64 | 已经上传成功的数据长度 |
2.14.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/multipart/preupload Content-Type: multipart/form-data; boundary=---------------------------40612316912668 Content-Length: xxx -----------------------------40612316912668 Content-Disposition: form-data; name="json"; filename="json" Content-Type: application/json {"file_name":"test.pptx","file_size":15135,"block_size":524288,"channel_count":4,"file_md5":"xxxxxxxxxxxxxxxxxxxxx"} -----------------------------40612316912668 Content-Disposition: form-data; name="data"; filename="data" Content-Type: application/octet-stream 文件分片数据 -----------------------------40612316912668-- |
输出示例:
{ "ret":0, "msg":"suc", "upload_key":"timi_test", "upload_state":1, "channel_count":4, "uploaded_data_len":0, "channel_list":[ { "id":1, "offset":0 }, { "id":2, "offset":524288 }, { "id":3, "offset":1048576 }, { "id":4, "offset":1572864 } ] } |
2.15 分片上传文档数据
2.15.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/multipart/upload |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来预上传一个本地文档
2.15.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 参数位置 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 | |
TOID | String | 是 | 用户ID,登录后获得 | |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 | |
upload_key | String | multipart/form-data json | 是 | 上传文件的唯一标识 |
channel | JSON Object | multipart/form-data json | 是 | 通道信息(包含该通道当前分片上传信息),{"id:"uint32 channelid,"offset":uint64 offset,"crc32":uint32 crc32} |
data | byte[] | multipart/form-data 二进制 | 是 | 文件数据 |
2.15.3 输出参数
参数名称 | 类型 | 描述 |
ret | int | 返回码 |
msg | string | 错误描述 |
upload_key | string | 上传文件的唯一标识,此后所有DocUploadPiece请求都需要带上该字段 |
upload_state | int | 上传状态 1:UploadNextPacket,需要上传下一分片; 2:UploadFinished,上传文件完成; 3:WaitOtherFinish,使用多个通道才会返回,表明当前通道已经上传完所有分片,需要等待其他通道上传完成 |
channel | JSON Object | 通道信息(包含该通道下个分片上传信息),{"id:"uint32 channelid,"offset":uint64 offset,"len":uint64 len} |
2.15.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/multipart/upload Content-Type: multipart/form-data; boundary=---------------------------40612316912668 Content-Length: xxx -----------------------------40612316912668 Content-Disposition: form-data; name="json"; filename="json" Content-Type: application/json {"upload_key":"timi_test","channel":{"id":xx,"offset":xxx,"crc32":xxx}} -----------------------------40612316912668 Content-Disposition: form-data; name="data"; filename="data" Content-Type: application/octet-stream 文件分片数据 -----------------------------40612316912668-- |
输出示例:
{ "ret":"x", "msg":"xxx", "upload_key":"timi_test", "uploadstate":1, "channel":{ "id":"xx", "offset":21 } } |
2.16 分片上传导入文档
2.16.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/doc/multipart/import |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用来预上传一个本地文档
2.16.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 参数位置 | 必选 | 描述 |
APPID | Integer | 是 | 企业AppID,企业接入时申请获得 | |
TOID | String | 是 | 用户ID,登录后获得 | |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 | |
upload_key | String | http post body | 是 | 上传文件的唯一标识 |
operation_id | string | multipart/form-data json | 是 | 目前只用于取消导入 |
folder_id | string | http post body | 是 | 文件夹id |
password | string | http post body | 是 | 当后台返回115(加密文件)或者112(输入密码错误),终端弹密码框,用户输入后,带上password重新调用此命令。 |
dst_doc_type | int | http post body | 是 | 目标文档类型(0:word,4:ppt) |
2.16.3 输出参数
参数名称 | 类型 | 描述 |
ret | int | 返回码 |
msg | string | 错误描述 |
upload_key | string | 上传文件的唯一标识 |
url | string | 文档url |
title | string | 文档title |
padType | string | 文档类型(string) |
domainId | uint64 | domainId |
localPadId | string | localPadId |
doc_type | int | 文档类型(int) |
doc_id | string | 文档id |
createdDate | string | 创建时间 |
2.16.4 示例
输入示例:
POST https://example.txdocs.qq.com/openapi/v1/doc/multipart/import Content-Type: application/x-www-form-urlencoded Content-Length: xxx upload_key=xxxxxxxxxxxxxxxx&operation_id=xxxxxxxxxxxxxxxxxxxxxxx&folder_id=xxxx |
输出示例:
{"ret":x,"msg":"xxx","upload_key":"timi_test","url":"xxx","title":"xxx","pad_type":"xxx","domain_id":xxx,"local_pad_id":"xxx"} |
3.权限相关接口
3.1设置权限接口
3.1.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/privilege/set |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用于设置文档权限
3.1.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | String | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
doc_id | String | 是 | 文档ID |
policy | Integer | 否 | 文档权限,0=私密,1=指定成员,2=任何人可查看,3=任何人可编辑 |
add | String | 否 | 添加/修改成员权限,Json 字串,可多个用户,例如: [{"type":1, "toid":"123","right":1},{"type":2, "toid":"456","right":2}] 具体字段说明见下方 |
*add.type | Integer | 是 | toid 类型,1=用户,2=群组 |
*add.toid | String | 是 | toid 用户ID |
*add.right | Integer | 是 | 权限类型,1=查看,2=编辑 |
del | String | 否 | 删除成员权限,Json 字串,可多个用户,例如: [{"type":1, "toid":"123"},{"type":2, "toid":"456"}] 具体字段说明见下方 |
*del.type | Integer | 是 | toid 类型,1=用户,2=群组 |
*del.toid | String | 是 | toid 用户ID |
clear | Integer | 否 | 清空所有成员权限,1=清空 |
adv_forbid_copy | Integer | 否 | 禁止查看者复制、保存为本地文件、打印内容,0=允许(默认),1=禁止 |
data_type | Ingeger | 否 | 权限类型,0=文档权限(文档、表格),1=填写权限(收集表)。默认值 0 |
*开头为相应Json的字段内容
3.1.3 输出参数
3.1.4 示例
输入示例:
https://example.txdocs.qq.com/openapi/v1/privilege/set doc_id=DY2NNWkpTck1YbkV4&policy=1&add=[{"type":1,"toid":"123","right":2}] |
输出示例:
{ "ret": 0, "msg": "ok" } |
3.2 读取权限接口
3.2.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/privilege/get |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用于获取文档权限
3.2.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | String | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
doc_id | String | 是 | 文档ID |
data_type | int | 否 | 权限类型,0=文档权限(文档、表格),1=填写权限(收集表)。默认值 0 |
3.2.3 输出参数
参数名称 | 类型 | 描述 |
policy | Integer | 文档权限,0=私密,1=指定成员,2=任何人可查看,3=任何人可编辑 |
member | String | 成员权限列表,Json 字串,可多个用户 |
member.type | Integer | toid 类型,1=用户,2=群组 |
member.toid | String | toid 用户ID |
member.right | Integer | 权限类型,1=查看,2=编辑 |
member.nick | String | 用户昵称 |
member.avatar | Sting/Array | 用户头像,群组为数组 |
adv_forbid_copy | Integer | 禁止查看者复制、保存为本地文件、打印内容,0=允许(默认),1=禁止 |
3.2.4 示例
输入示例:
https://example.txdocs.qq.com/openapi/v1/privilege/get doc_id=DY2NNWkpTck1YbkV4 |
输出示例:
{ "ret": 0, "msg": "ok", "data": { "policy": 1, "member": { [ { "type": 1, "toid": 123, "right": 2, "nick": "昵称" } ] }, "adv_forbid_copy": 0 } } |
3.3 第三方权限修改通知接口
3.3.1 接口描述
描述 | 定义 |
接口名 | /openapi/v1/privilege/change |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
本接口用于获取文档权限
3.3.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | String | 是 | 企业AppID,企业接入时申请获得 |
TOID | String | 是 | 用户ID,登录后获得 |
TOID_KEY | String | 是 | 用户登录Key,登录后获得 |
doc_id | String | 是 | 文档ID |
3.3.3 输出参数
无
3.3.4 示例
输入示例:
https://example.txdocs.qq.com/openapi/v1/privilege/change doc_id=DY2NNWkpTck1YbkV4 |
输出示例:
{ "ret": 0, "msg": "ok", } |
4.打开文档接口
4.1 接口描述
描述 | 定义 |
接口名 | https://example.txdocs.qq.com/openapi/v1/jump/open |
请求方式 | GET |
本接口用于打开文档。
4.2 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见公共请求参数。
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 公共参数 |
TIMESTAMP | Integer | 是 | 公共参数 |
NONCE | Integer | 是 | 公共参数 |
SIGNATURE | String | 是 | 公共参数 |
doc_id | String | 否 | 文档ID,此参数也必须被签名 |
doc_type | Integer | 是 | 文档类型 |
url_type | Integer | 是 | 跳转类型 0=文档编辑页 1=创建页 |
下面跳转鉴权方式二选一,每次只能传一种方式
如果使用企业微信票据(third_token),需要传下列参数
参数名称 | 类型 | 必选 | 描述 |
third_token | String | 是 | 第三方票据,用户向第三方验证用户信息 |
login_type | Integer | 是 | 填 0 |
如果使用第三方回调票据(third_token),需要传下列参数
参数名称 | 类型 | 必选 | 描述 |
third_token | String | 是 | 第三方票据,用户向第三方验证用户信息 |
login_type | Integer | 是 | 填 3 |
如果使用auth下发的 jump_code,需要传下列参数
参数名称 | 类型 | 必选 | 描述 |
jump_code | String | 是 | 使用auth接口提供的jump_code进行登录 |
4.3 输出参数
无。该接口会302跳转打开文档。接入方在后台生成该接口后,返回到终端。终端直接打开该地址即可。
4.4 示例
输入示例:
https://example.txdocs.qq.com/openapi/v1/jump/open?APPID=111&TIMESTAMP=222&NONCE=333&SIGNATURE=SSS&third_token =BBB&doc_id=DY2NNWkpTck1YbkV4 |
六.第三方提供的接口
第三方提供的接口名称 | 接口功能(腾讯文档回调使用) |
https://third.com/get_third_userinfo | 查询第三方用户信息 |
https://third.com/callback | 接收腾讯文档开放平台的事件通知(如文档被删除等) |
1 用户信息回调
下述示例中,third.com是一个示例,实际调用的是第三方提供的回调域名。
1.1 接口描述
本接口由第三方提供,用于腾讯文档侧调用拉取信息以验证相关信息
描述 | 定义 |
接口地址 | https://third.com/get_third_userinfo |
接口说明 | 本接口由第三方提供,用于腾讯文档侧调用拉取信息以验证相关信息 第三方注册时,在注册信息相关项中填写提供url |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
1.2 输入参数
参数名称 | 类型 | 必选 | 描述 |
APPID | Integer | 是 | 应用注册成功后获取 |
TIMESTAMP | Integer | 是 | 当前 UINX 时间戳,即发起 API 请求的时间,如果时间与当前时间相差过大,会引起签名过期错误 |
NONCE | Integer | 是 | 第三方请求时带的随机正整数 |
SIGNATURE | String | 是 | 请求签名,用来验证此次请求的合法性,具体计算方法见【接口鉴权】 |
third_token | String | 是 | 第三方用户 token |
1.3 输出参数
参数名称 | 类型 | 必选 | 描述 |
ret | int | 是 | 返回码, 返回0表示成功, 其它错误由第三方自定义 |
msg | string | 是 | 返回信息, 错误时给出相应信息 |
data | object | 是 | 返回数据字段 |
data.user_id | string | 是 | 第三方内部用于标识用户ID,长度不要大于 64 字节 |
data.avator | string | 是 | 第三方提供的用户头像地址,请放开对 *.docs.qq.com 的防盗链,长度不要大于 256 字节 |
1.4 示例
输入示例:
POST https://third.com/get_third_userinfo?SIGNATURE=%2Bt4T%2BbiMCZC7VP%2FPASYrb6pWS9Q%3D APPID=1001&NONCE=4529053332324&TIMESTAME=1465185768&third_token=xxxxx |
输出示例:
{ "ret": 0, "msg": "ok", "data": { "user_id": "ertuydskTYROJBsdf", "nick": "uname", "avator": "http://avator.thrid.com/abc.jpg" } } |
2 通知回调
2.1 接口描述
本接口由第三方提供,用于腾讯文档侧调用以通知第三方文档变动相关事件
描述 | 定义 |
接口地址 | https://third.com/callback |
接口说明 | 本接口由第三方提供,用于腾讯文档侧调用以通知第三方文档变动相关事件 第三方注册时,在注册信息相关项中填写提供url |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
2.2 输入参数
参数名称 | 类型 | 必选 | 描述 |
APPID | Int | 是 | 企业AppID,企业接入时申请获得 |
TIMESTAMP | Integer | 是 | 当前 UINX 时间戳,即发起 API 请求的时间,如果时间与当前时间相差过大,会引起签名过期错误 |
SIGNATURE | String | 是 | 请求签名,用来验证此次请求的合法性,具体计算方法见【接口鉴权】 |
type | int | 是 | 事件类型 |
from_toid | string | 是 | 操作用户id |
doc_id | string | 否 | 相关文档id |
to_toid | string | 否 | 涉及到相关用户id |
third_uid | string | 是 | 操作用户的third_uid |
2.3 事件类型
id | 描述 |
1 | 标题修改 |
2 | 文档修改 |
4 | 打开文档 |
2.4 输出参数
参数名称 | 类型 | 必选 | 描述 |
ret | int | 是 | 返回码, 返回0表示成功, 其它错误由第三方自定义 |
msg | string | 是 | 返回信息, 错误时给出相应信息 |
2.5 示例
输入示例:
POST https://third.com/callback?SIGNATURE=41yS5Vpyjww7+PnopbZdVRp0hss%3D APPID=1001&TIMESTAME=1465185768&type=1&from_toid=xxx&to_toid=yyy&doc_id=zzzzz |
输出示例:
{ "ret": 0, "msg": "ok" } |
3 鉴权回调
3.1 接口描述
本接口由第三方提供,用于腾讯文档侧调用以获取某一用户对于某一篇文档所拥有的权限
描述 | 定义 |
接口地址 | https://third.com/txdocs/privilege_callback |
接口说明 | 本接口由第三方提供,用于腾讯文档侧调用以通知第三方文档变动相关事件 第三方注册时,在注册信息相关项中填写提供url |
请求方式 | POST |
请求格式 | application/x-www-form-urlencoded |
3.2 输入参数
参数名称 | 类型 | 必选 | 描述 |
APPID | Int | 是 | 企业AppID,企业接入时申请获得 |
TIMESTAMP | Integer | 是 | 当前 UINX 时间戳,即发起 API 请求的时间,如果时间与当前时间相差过大,会引起签名过期错误 |
SIGNATURE | String | 是 | 请求签名,用来验证此次请求的合法性,具体计算方法见【接口鉴权】 |
doc_id | string | 是 | 文档id |
user_id | string | 是 | 第三方鉴权回调返回的user_id(如果为空,返回匿名操作权限) |
sig | string | 否 | 腾讯文档加密签名,第三方用公钥解密,校验请求来源 |
3.3 输出参数
参数名称 | 类型 | 必选 | 描述 |
ret | int | 是 | 返回码, 返回0表示成功, 其它错误由第三方自定义 |
msg | string | 是 | 返回信息, 错误时给出相应信息 |
mode | int | 是 | 0: 无权限 1: 可读 2: 可写 |
3.4 示例
输入示例:
POST https://third.com/txdocs/privilege_callback?doc_id=300000000$acdddddddd&user_SIGNATURE=41yS5Vpyjww7+PnopbZdVRp0hss%3D APPID=1001&TIMESTAME=1465185768&user_id=yyy&doc_id=zzzzz |
输出示例:
{ "ret": 0, "msg": "ok", "mode":1 } |