如何调用服务端 API

开发前须知

1. 在调用服务端 API 之前，需要先创建应用，才可以获取权限和凭证。了解应用类型和开发流程。
2. 在调用服务端 API 之前，确保已设置 API 所需要的权限。权限可在开发者后台-权限申请处申请。
3. 在调用服务端 API 之前，确保已获取 API 所需要的凭证（token），并加入到请求中。凭证获取流程可见API 凭证。
4. 在调用服务端 API 之前，请在开发者后台-安全设置设置 IP 白名单（服务端接口限制了指定 IP 的请求才可调用）。
5. API 调用时，需要通过 WPS-3 算法进行签名鉴权，了解签名说明。
6. 了解常用术语概念定义将有助于你正确调用接口，了解名词解释。
7. API调用报错时将返回错误状态码，不同状态码含义不同。状态码含义可见状态码说明。
8. 应用也可通过订阅WPS协作提供的事件，获取应用消息通知，了解事件订阅。

API 文档约定格式

请求：
	请求说明         //接口调用地址、方式、签名、支持调用的应用类型、所需权限
	请求头           //HTTP请求中的header参数，要求使用WPS-3签名
	路径参数         //这部分参数需要放置在URL中，文档中一般以：开头
	查询参数         //这部分参数需要在URL后使用？进行拼接，多个查询参数间用 & 分隔
	请求地址示例      //一般以{请求方式}+{请求地址}+{路径参数}+{查询参数}形式呈现
	请求体           //这部分参数需要放置在body中，一般为json格式
	请求体示例        //对应API成功请求参数的样例
响应：
	响应体           //一次API调用后，HTTP响应中body部分的内容
	响应体示例        //API成功请求结果的样例

API 调用流程

1. 申请 API 调用所需权限

登录开发者后台，选择进入具体应用，在权限申请模块添加所需权限，并申请权限开通：

• 企业自建应用：添加申请权限后，页面提示敏感项修改，可提交审核到本企业管理后台，由超管审核开通并授权。
• 第三方企业应用：添加申请权限后，页面提示敏感项修改，需创建应用版本并申请上架。第三方企业超管先在企业管理后台进行审核，而后WPS协作官方再进行审核，审核通过后权限开通。

目前WPS协作需要申请的权限如下表所示：

scope	权限名称	说明
corp_contacts.read	访问企业通讯录	允许应用进行企业通讯录的查询操作
corp_contacts.write	更新企业通讯录	允许应用进行企业通讯录的增删改操作
corp_contacts.user_phone.read	获取企业成员的手机号信息	获取企业成员的手机号信息
corp_contacts.user_email.read	获取企业成员的邮箱信息	获取企业成员的邮箱信息
corp_contacts.user_gender.read	获取企业成员的性别信息	获取企业成员的性别信息
contact_access_control	企业通讯录设置	允许应用进行企业通讯录的可见性等规则的设置
xz_message	消息推送	允许应用通过接口发送消息
xz_singlechat_mgr	单聊管理	允许应用对WPS协作单聊操作，如创建单聊
xz_chat_mgr	群聊管理	允许应用对WPS协作群聊操作 ，如创建群聊、获取群聊信息等
xz_message.user2bot.read	获取用户发给机器人的单聊消息	用于“接收消息”事件，获取用户发给机器人的单聊消息
xz_message.group2bot.read	获取用户在群聊中@机器人的消息	用于“接收消息”事件，获取用户在群聊中@机器人的消息
xz_file_mgr	文件管理	允许管理WPS协作文件
xz_app.read	应用信息	获取WPS协作应用信息
xz_approve.write	创建及更新审批信息	创建及更新审批信息
xz_approve.read	查看审批信息	查看审批信息
calendar.write	更新用户日程/待办信息	获得更新用户日程/待办相关能力，包括创建日程/待办，删除日程/待办

2. 获取 API 调用所需凭证

接口访问凭证分为用户授权凭证（access_token）、应用授权凭证（app_token）、企业授权凭证（company_token）。具体获取流程请参考API 凭证概述。