微伴助手开放接口对接文档

version: 0.4

注1：微伴助手开放接口已经开放公测，进入微伴后台-应用中心-开放平台接入以获取企业标识（corp_id），企业API调用凭据（secret）
注2：系统内所有的时间相关字段如果没有特别说明都是以秒为单位。
注3：目前open api并未提供测试模式，请研发调用的时候注意，测试完成的时候及时删除测试数据。

阅读说明

微伴助手通过开放接口（Open API）为接入企业提供进一步集成和个性化定制的能力。

所有接口都使用 HTTPS 协议，JSON 数据格式和 UTF-8 编码。

接口使用 GET 和 POST 两种操作，其他类型操作（如 PUT）皆不会用到。

GET 类型操作中可能需要 query参数。

说明: query参数是放入url中的参数，例如 API https://open.weibanzhushou.com/some_api 在添加 query 参数 access_token 和 id 后完整请求为：
https://open.weibanzhushou.com/some_api?access_token=xxx&id=xxx

另外，POST 类型操作中除了 query参数 外还可能需要提供 body参数。具体会在相应业务 API 文档中介绍。

请求返回值中总是包含 errcode 和 errmsg 字段，称为基础返回字段。用于描述请求的成功状态，其定义如下：

字段	类型	说明
errcode	int	状态码，0为正常，非0代表错误。错误码见下文说明
errmsg	str	错误信息，成功时为'ok'，错误时会以中文方式显示错误原因

样例：

// 正确样例
{
  "errcode": 0,
  "errmsg": "ok"
}
// 错误样例
{
  "errcode": 10001,
  "errmsg": "认证错误：请提供正确的access_token"
}

错误码绝大多数情况为五位数字(例如10001），其中以「1」开头的为 全局错误码 ，以「2」开头的为 业务错误码。
全局错误码定义见：全局错误码。
业务错误码则会在各个接口对应文档中说明。

注：业务错误码也是全局唯一的。

接入准备

进入微伴后台-应用管理-API接入以获取企业标识（corp_id），企业API调用凭据（secret），如图所示。

首先您将会在界面上看到企业的corp_id，这是调用接口的重要凭据之一。

点击创建secret,您将会看到OpenAPI使用声明。您需要仔细阅读并确认知晓OpenAPI的secret泄露可能造成的风险，若您同意使用声明的内容，请点击同意，若不同意，则无法使用OpenAPI。

同意后将会弹出创建secret窗口。

点击确定后，会为您展示OpenAPI的secret，请妥善保管。

利用以上操作获取的corp_id和secret来获取 API 调用凭据（access_token），见：获取访问凭据。

重新获取secret

由于微伴不再保存OpenAPI的secret信息，若您不慎遗失了secret，您需要到微伴后台重新获取secret。

使用条款

如果您之前没有同意OpenAPI的使用说明，您将会看到OpenAPI的使用说明。

如您需要继续使用OpenAPI的服务，需要仔细阅读并确认知晓OpenAPI的secret泄露可能造成的风险，若您同意使用声明的内容，请点击同意，若不同意，您的access_token将会失效，且无法使用OpenAPI的相关功能。

同意之后您可以选择重新获取新的secret。

与企业微信API的差异

由于微伴开放接口在数据接口和功能上与企业微信API有较多重合，因此在设计时充分考虑了熟悉企业微信文档的接入者现有的使用习惯。

然而，由于在系统设计、数据结构和功能上并非完全一致，在具体 API 的路径、概念名称、参数和返回值数据结构等地方存在与企业微信不一致的地方，希望开发者注意其中的差异。

需要特别注意的差异：

员工概念的差异：微伴系统中员工对应 staff，而企业微信中员工对应 user。微伴系统内的 staff_id 皆对应企业微信成员管理API 中的 userid 字段。此字段在企业微信后台也可以查看到。

个人标签的差异：由于企业微信并未开放操作企业微信中员工个人标签的能力，微伴系统中的个人标签是仅在微伴系统内维护的标签，并不会同步到企业微信。

OpenAPI基本介绍

微伴助手开放接口对接文档#

阅读说明#

接入准备#

重新获取secret#