腾讯文档开放API

2. API 概览

3. 开发者与应用注册

开发者需要先到官网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.公共参数

公共参数是用于标识用户和接口鉴权目的的参数，如非必要，在每个接口单独的接口文档中不再对这些参数进行说明，但每次请求均需要携带这些参数，才能正常发起请求。

为避免接口参数冲突，公共参数的参数名为全大写字母。

4.接口鉴权

获取登录态时需要对接口进行签名，腾讯文档开放平台在调用第三方接口时，第三方平台也需要对请求进行签名校验已确保请求来源合法。

以 登录接口(/openapi/v1/user/auth) 为例，发送的请求参数如下：

注意：这里只是例子，用于说明接口签名的过程，实际接口参数可能与此不同

4.1 对参数排序

首先对所有请求参数按参数名的字典序（ ASCII 码）升序排序

注意：

1）只按参数名进行排序，参数值保持对应即可，不参与比大小；

2）按 ASCII 码比大小，如 InstanceIds.2 要排在 InstanceIds.12 后面，不是按字母表，也不是按数值。

用户可以借助编程语言中的相关排序函数来实现这一功能，如 php 中的 ksort 函数。

上述示例参数的排序结果如下：

4.2 拼接请求字符串

此步骤生成请求字符串。 将把上一步排序好的请求参数格式化成“参数名称”=“参数值”的形式

注意：“参数名称“和“参数值”为原始值而非url编码后的值。

然后将格式化后的各个参数用"&"拼接在一起。

最终生成的请求字符串为:

4.1.3 拼接签名原文字符串

此步骤生成签名原文字符串。 签名原文字符串由以下几个参数构成:

• 请求方法: 支持 POST 和 GET 方式，这里使用 GET 请求，注意方法为全大写。
  
• 请求主机: 根据实际请求的域名填写
  
• 例如：example.txdocs.qq.com
  
• 请求路径: 即接口名称
  
• 请求字符串: 即上一步生成的请求字符串
  

签名原文串的拼接规则为:

请求方法 + 请求域名 +请求路径 + ? + 请求字符串

示例的拼接结果为：

4.3 生成签名串

此步骤生成签名串。 首先使用 HMAC-SHA1 算法对上一步中获得的签名原文字符串进行签名，然后将生成的签名串使用 Base64 进行编码，即可获得最终的签名串。

具体代码如下，以 PHP 语言为例:

最终得到的签名串为:

使用其它程序设计语言开发时，可用上面示例中的原文进行签名验证，得到的签名串与例子中的一致即可。

4.4 签名串编码

生成的签名串并不能直接作为请求参数，需要对其进行 URL 编码。

注意：如果用户的请求方法是 GET，或者请求方法为 POST 同时 Content-Type 为 application/x-www-form-urlencoded ，则对所有请求参数值均需要做 URL 编码。

非 ASCII 字符在 URL 编码前需要先以 UTF-8 进行编码。

如上一步生成的签名串为:

经过 urlencode 之后，最终得到的签名串请求参数(SIGNTURE)为：

注意：有些编程语言的 http 库会自动为所有参数进行 urlencode ，在这种情况下，就不需要对签名串进行 URL 编码了，否则两次 URL 编码会导致签名失败。

5.错误码

5.1 网关返回的错误码

5.1 CGI返回的错误码(部分)

5. API接口详情

下述接口示例中均以example.txdocs.qq.com为HOST来进行举例，实际请求时请使用申请到的第三方独立域名，无独立域名则使用通用域名tob.txdocs.qq.com。

另外，如果用户的请求方法是 GET，或者请求方法为 POST 同时 Content-Type 为 application/x-www-form-urlencoded ，则对所有请求参数值均需要做 URL 编码。（若出现签名错误、参数错误等提示，请检查是否有正确地URL编码）

1.登录相关接口

1.1 接口描述

本接口用于获取用户的登录态

注意：此接口需要签名验证

1.2 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见公共请求参数。

下面登录方式三选一，每次只能传一种方式

企业微信 Token/Code 登录时，传下列参数

QQ 登录时，传下列参数

微信登录时，传下列参数

第三方回调登录时，传下列参数

1.3 输出参数

若是采用第三方回调登录的方式，如果登录时回调第三方提供的用户信息回调服务出错，则此登录接口会返回错误：｛“cgicode”:10003, "ret":43810, "msg":"0x16184 response error, msg=third toid serv error｝

1.4 示例

输入示例：

输出示例：

2.文档相关接口

2.1 创建文档

2.1.1 接口描述

本接口用来创建文档。若要打开文档，请使用/openapi/v1/jump/open接口（4.1）。

2.1.2 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见公共请求参数。

2.1.3. 输出参数

2.1.4. 示例

输入示例：

输出示例：

2.2 删除文档

2.2.1 接口描述

本接口用来删除文档，此接口会校验toid是否是该文档的拥有者（拥有者并非一定是创建者，因为拥有者可以转让，参考 /openapi/v1/doc/trans）

2.2.2 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见公共请求参数。

2.2.3 输出参数

无

2.2.4 示例

输入示例：

输出示例：

2.3 还原文档

2.3.1 接口描述

本接口用来还原文档，此接口会校验toid是否是该文档的拥有者（拥有者并非一定是创建者，因为拥有者可以转让，参考 /openapi/v1/doc/trans）

2.3.2 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见公共请求参数。