Skip to content

Latest commit

 

History

History
4623 lines (4256 loc) · 229 KB

wechat.md

File metadata and controls

4623 lines (4256 loc) · 229 KB
Raw

wechat

欢迎你，开发者

当你打开此页面，我们期待你成为企业号的开发者。

企业号是微信为企业客户提供的移动应用入口。它帮助企业建立员工、上下游供应链与企业IT系统间的连接。利用企业号，企业或第三方合作伙伴可以帮助企业快速、低成本的实现高质量的移动轻应用，实现生产、管理、协作、运营的移动化。我们有信心，帮助你及每一位企业号开发者，提升开发效率，降低开发成本与难度，确保企业应用的活跃。

我们也坚信企业号能帮助你获得更多的商业机会，服务更多的企业客户，从而不断的提升你的价值。你的成功也将是企业号的成功。

当你成功申领一个企业号后，你可以登录企业号的管理页面，导入通讯录、配置应用、邀请成员关注该企业号，也可以通过应用向成员发送文本、图文、文件、视频、音频等多媒体消息。通过简单的配置，你就可以自动回复成员发送的消息，实现公告通知、知识管理、企业文化建设、手机企业通讯录等基本的企业应用。

你还可以通过本文档所描述的接口，建立企业号同企业应用间的连接，实现更多丰富且个性化的企业移动应用。

建立连接

连接将使你的企业号更具价值，你可以使用以下三种方式，连接你的企业号及企业应用：

  1. 企业应用调用企业号提供的接口，管理或查询企业号后台所管理的资源、或给成员发送消息等，以下称主动调用模式。
  2. 企业号把用户发送的消息或用户触发的事件推送给企业应用，由企业应用处理，以下称回调模式。
  3. 用户在微信中阅读企业应用下发的H5页面，该页面可以调用微信提供的原生接口，使用微信开放的终端能力，以下称JSAPI模式。

通过这三种连接方式的结合，你可以在企业号中建立功能强大的移动轻应用，并依托微信数亿活跃用户，帮助企业方便、快捷地实现应用的部署，并确保应用的活跃度。

主动调用

主动调用是最基本的连接模式，当你的应用调用企业号时，需使用https协议、Json数据格式、UTF8编码，访问域名为https://qyapi.weixin.qq.com，数据包不需要加密。

在每次主动调用企业号接口时需要带上AccessToken参数。AccessToken参数由CorpID和Secret换取。

[CorpID](/wiki/index.php?title=CorpID" title="CorpID)是企业号的标识，每个企业号拥有一个唯一的CorpID；Secret是管理组凭证密钥。

系统管理员可通过管理端的权限管理功能创建管理组，分配管理组对应用、通讯录、接口的访问权限。完成后，管理组即可获得唯一的secret。系统管理员可通过权限管理查看所有管理组的secret，其他管理员可通过设置中的开发者凭据查看。

当企业应用调用企业号接口时，企业号后台为根据此次访问的AccessToken,校验访问的合法性以及所对应的管理组的管理权限以返回相应的结果。

注：你应该审慎配置管理组的权限，够用即好，权限过大会增加误操作可能性及信息安全隐患。

获取AccessToken

AccessToken是企业号的全局唯一票据，调用接口时需携带AccessToken。

AccessToken需要用CorpID和Secret来换取，不同的Secret会返回不同的AccessToken。正常情况下AccessToken有效期为7200秒，有效期内重复获取返回相同结果，并自动续期。

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=id&corpsecret=secrect

  • 参数说明
参数必须说明
corpid 是 企业Id
corpsecret 是 管理组的凭证密钥
  • 权限说明
每个secret代表了对应用、通讯录、接口的不同权限；不同的管理组拥有不同的secret。
  • 返回说明
a)正确的Json返回结果: 
{
   "access_token": "accesstoken000001",
}
参数 说明
access_token 获取到的凭证
 b)错误的Json返回示例: 
{
   "errcode": 43003,
   "errmsg": "require https"
}

主动调用的频率限制

当你获取到AccessToken时，你的应用就可以成功调用企业号后台所提供的各种接口以管理或访问企业号后台的资源或给企业号成员发消息。

为了防止企业应用的程序错误而引发企业号服务器负载异常，默认情况下，每个企业号调用接口都有一定的频率限制，当超过此限制时，调用对应接口会收到相应错误码。

以下是当前默认的频率限制，企业号后台可能会根据运营情况调整此阈值：

  • 基础频率
每企业调用单个cgi/api不可超过1000次/分，30000次/小时

每ip调用单个cgi/api不可超过2000次/分，60000次/小时

  • 发消息频率
每企业不可超过帐号上限数*30人次/天
  • 创建帐号频率
每企业创建帐号数不可超过帐号上限数*3/月
## 目录
## **回调模式** 在回调模式下，企业不仅可以主动调用企业号接口，还可以接收用户的消息或事件。**接收的信息使用XML数据格式、UTF8编码，并以AES方式加密**。

企业号的每个应用都有自己的回调模式开关。在管理端开启并设置好相关参数后，此应用的回调模式才生效。

针对加解密的处理，微信提供了各种语言的库，企业可以在附录中下载。

开启应用的回调模式

当你开启应用的回调模式时，企业号会要求你填写应用的URL、Token、EncodingAESKey三个参数。

URL是企业应用接收企业号推送请求的访问协议和地址，支持http或https协议。

Token可由企业任意填写，用于生成签名。

EncodingAESKey用于消息体的加密，是AES密钥的Base64编码。

验证URL、Token以及加密的详细处理请参考后续'接收消息时的加解密处理'的章节。

Hdms.png
**验证URL有效性**

当你提交以上信息时，企业号将发送GET请求到填写的URL上，GET请求携带四个参数，企业在获取时需要做urldecode处理，否则会验证不成功。

参数描述是否必带
msg_signature 微信加密签名，msg_signature结合了企业填写的token、请求中的timestamp、nonce参数、加密的消息体 是
timestamp 时间戳 是
nonce 随机数 是
echostr 加密的随机字符串，以msg_encrypt格式提供。需要解密并返回echostr明文，解密后有random、msg_len、msg、$CorpID四个字段，其中msg即为echostr明文 首次校验时必带
 企业通过参数msg_signature对请求进行校验，如果确认此次GET请求来自企业号，那么**企业应用对echostr参数解密并原样返回echostr明文(不能加引号)**，则接入验证生效，回调模式才能开启。

后续回调企业时都会在请求URL中带上以上参数（echostr除外），校验方式与首次验证URL一致。

使用回调模式

企业号在回调企业URL时，会对消息体本身做AES加密，以XML格式POST到企业应用的URL上；企业在被动响应时，也需要对数据加密，以XML格式返回给微信。企业的回复支持文本、图片、语音、视频、图文等格式。

微信服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次。如果在调试中，发现员工无法收到响应的消息，可以检查是否消息处理超时。

当接收成功后，http头部返回200表示接收ok，其他错误码一律当做失败并发起重试

关于重试的消息排重，有msgid的消息推荐使用msgid排重。事件类型消息推荐使用FromUserName + CreateTime排重。

假如企业无法保证在五秒内处理并回复，可以直接回复空串，企业号不会对此作任何处理，并且不会发起重试。这种情况下，可以使用发消息接口进行异步回复。

假设企业回调URL为https://api.3dept.com。

  • 请求说明：
https://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS&timestamp=13500001234&nonce=123412323
  • 回调数据格式：
<xml>
   <ToUserName><![CDATA[toUser]]</ToUserName>
   <AgentID><![CDATA[toAgentID]]</AgentID>
   <Encrypt><![CDATA[msg_encrypt]]</Encrypt>
</xml>

1.msg_encrypt为经过加密的密文
2.AgentID为接收的应用id，可在应用的设置页面获取
3.ToUserName为企业号的CorpID

企业需要对msg_signature进行校验，并解密msg_encrypt，得出msg的原文。

  • 被动响应给微信的数据格式：
<xml>
   <Encrypt><![CDATA[msg_encrypt]]></Encrypt>
   <MsgSignature><![CDATA[msg_signature]]></MsgSignature>
   <TimeStamp>timestamp</TimeStamp>
   <Nonce><![CDATA[nonce]]></Nonce>
</xml>

1.msg_encrypt为经过加密的密文，算法参见附录
2.MsgSignature为签名，算法参见附录
3.TimeStamp为时间戳，Nonce为随机数，由企业自行生成

接收消息时的加解密处理

企业可以直接使用微信提供的库进行加解密的处理，目前提供的有c++/python/php/java/c#等语言版本。代码提供了解密、加密、验证URL三个接口，企业可根据自身需要下载(参见附录)。以下为库函数的使用说明(以c++为例)，更详细的加解密方案请参考附录。

1、解密函数

int DecryptMsg(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sPostData, string &sMsg);
  • 参数说明
参数必须说明
sMsgSignature 是 从回调URL中获取的msg_signature参数
sTimeStamp 是 从回调URL中获取的timestamp参数
sNonce 是 从回调URL中获取的nonce参数
sPostData 是 从回调URL中获取的整个post数据
sMsg 是 用于返回解密后的msg，以xml组织
  • 返回说明
请参阅附录加解密部分。

2、加密函数

int EncryptMsg(const string &sReplyMsg, const string &sTimeStamp, const string &sNonce, string &sEncryptMsg);
  • 参数说明
参数必须说明
sReplyMsg 是 返回的消息体原文
sTimeStamp 是 时间戳，调用方生成
sNonce 是 随机数，调用方生成
sEncryptMsg 是 用于返回的密文，以xml组织
  • 返回说明
请参阅附录加解密部分。

3、验证URL函数

int VerifyURL(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sEchoStr, string &sReplyEchoStr);
  • 参数说明
参数必须说明
sMsgSignature 是 从回调URL中获取的msg_signature参数
sTimeStamp 是 从回调URL中获取的timestamp参数
sNonce 是 从回调URL中获取的nonce参数
sEchoStr 是 从回调URL中获取的echostr参数。注意，此参数必须是urldecode后的值
sReplyEchoStr 是 解密后的echostr，用于回包。注意，必须原样返回，不要做加引号或其它处理
  • 返回说明
请参阅附录加解密部分。

获取微信服务器的ip段

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/getcallbackip?access_token=ACCESS_TOKEN

  • 参数说明
参数 必须说明
access_token 是 调用接口凭证
  • 返回结果
{
   "ip_list": ["101.226.103.*", "101.226.62.*"]
}

管理通讯录

企业号通讯录具备完全开放的接口，你的应用可以调用这些接口管理部门、成员和标签。

你的应用也可以使用部门、成员、标签发消息，或更改应用的可见范围。

注意，每个部门的直属员工上限为1000个；出于安全考虑，某些接口需要在管理端有明确的授权。

管理部门

## 目录
### **创建部门**
  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/department/create?access_token=ACCESS_TOKEN

请求包结构体为:

{
   "name": "广州研发中心",
   "parentid": "1",
   "order": "1"
}
  • 参数说明
参数必须说明
access_token 是 调用接口凭证
name 是 部门名称。长度限制为1~64个字符
parentid 是 父亲部门id。根部门id为1
order 否 在父部门中的次序。从1开始，数字越大排序越靠后
  • 权限说明
管理员须拥有“操作通讯录”的接口权限，以及父部门的管理权限。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "created",
   "id": 2
}
参数说明
errcode 返回码
errmsg 对返回码的文本描述内容
id 创建的部门id

更新部门

  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/department/update?access_token=ACCESS_TOKEN

请求包结构体为（如果非必须的字段未指定，则不更新该字段之前的设置值）:

{
   "id": 2,
   "name": "广州研发中心",
   "parentid": "1",
   "order": "1"
}
  • 参数说明
参数 必须说明
access_token 是 调用接口凭证
id 是 部门id
name 否 更新的部门名称。长度限制为1~64个字符。修改部门名称时指定该参数
parentid 否 父亲部门id。根部门id为1
order 否 在父部门中的次序。从1开始，数字越大排序越靠后
  • 权限说明
管理员须拥有“操作通讯录”的接口权限，以及该部门的管理权限。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "updated"
}

删除部门

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/department/delete?access_token=ACCESS_TOKEN&amp;id=2

  • 参数说明
参数 必须说明
access_token 是 调用接口凭证
id 是 部门id。（注：不能删除根部门；不能删除含有子部门、成员的部门）
  • 权限说明
管理员须拥有“操作通讯录”的接口权限，以及该部门的管理权限。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "deleted"
}

获取部门列表

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/department/list?access_token=ACCESS_TOKEN

  • 参数说明
参数 必须说明
access_token 是 调用接口凭证
  • 权限说明
管理员须拥有’获取部门列表’的接口权限，以及对部门的查看权限。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "ok",
   "department": [
       {
           "id": 2,
           "name": "广州研发中心",
           "parentid": 1
       },
       {
           "id": 3
           "name": "邮箱产品部",
           "parentid": 2
       }
   ]
}
参数说明
errcode 返回码
errmsg 对返回码的文本描述内容
department 部门列表数据。以部门的order字段从小到大排列
id 部门id
name 部门名称
parentid 父亲部门id。根部门为1

管理成员

## 目录
### **创建成员**
  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/user/create?access_token=ACCESS_TOKEN

请求包结构体为:

{
   "userid": "zhangsan",
   "name": "张三",
   "department": [1, 2],
   "position": "产品经理",
   "mobile": "15913215421",
   "email": "[email protected]",
   "weixinid": "zhangsan4dev",
   "extattr": {"attrs":[{"name":"爱好","value":"旅游"},{"name":"卡号","value":"1234567234"}]}
}
  • 参数说明
参数必须说明
access_token 是 调用接口凭证
userid 是 员工UserID。对应管理端的帐号，企业内必须唯一。长度为1~64个字符
name 是 成员名称。长度为1~64个字符
department 否 成员所属部门id列表。注意，每个部门的直属员工上限为1000个
position 否 职位信息。长度为0~64个字符
mobile 否 手机号码。企业内必须唯一，mobile/weixinid/email三者不能同时为空
email 否 邮箱。长度为0~64个字符。企业内必须唯一
weixinid 否 微信号。企业内必须唯一。（注意：是微信号，不是微信的名字）
extattr 否 扩展属性。扩展属性需要在WEB管理端创建后才生效，否则忽略未知属性的赋值
  • 权限说明
管理员须拥有“操作通讯录”的接口权限，以及指定部门的管理权限。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "created"
}

更新成员

  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/user/update?access_token=ACCESS_TOKEN

请求包示例如下（如果非必须的字段未指定，则不更新该字段之前的设置值）:

{
   "userid": "zhangsan",
   "name": "李四",
   "department": [1],
   "position": "后台工程师",
   "mobile": "15913215421",
   "email": "[email protected]",
   "weixinid": "lisifordev",
   "enable": 1,
   "extattr": {"attrs":[{"name":"爱好","value":"旅游"},{"name":"卡号","value":"1234567234"}]}
}
  • 参数说明
参数必须说明
access_token 是 调用接口凭证
userid 是 员工UserID。对应管理端的帐号，企业内必须唯一。长度为1~64个字符
name 否 成员名称。长度为0~64个字符
department 否 成员所属部门id列表。注意，每个部门的直属员工上限为1000个
position 否 职位信息。长度为0~64个字符
mobile 否 手机号码。企业内必须唯一，mobile/weixinid/email三者不能同时为空
email 否 邮箱。长度为0~64个字符。企业内必须唯一
weixinid 否 微信号。企业内必须唯一。（注意：是微信号，不是微信的名字）
enable 否 启用/禁用成员。1表示启用成员，0表示禁用成员
extattr 否 扩展属性。扩展属性需要在WEB管理端创建后才生效，否则忽略未知属性的赋值
  • 权限说明
管理员须拥有“操作通讯录”的接口权限，以及指定部门、成员的管理权限。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "updated"
}

删除成员

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/user/delete?access_token=ACCESS_TOKEN&amp;userid=lisi

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
userid 是 员工UserID。对应管理端的帐号
  • 权限说明
管理员须拥有“操作通讯录”的接口权限，以及指定部门、成员的管理权限。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "deleted"
}

批量删除成员

  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/user/batchdelete?access_token=ACCESS_TOKEN

请求包结构体为:

{
   "useridlist": ["zhangsan", "lisi"]
}
  • 参数说明
参数必须说明
access_token 是 调用接口凭证
useridlist 是 员工UserID列表。对应管理端的帐号
  • 权限说明
管理员须拥有“操作通讯录”的接口权限，以及指定部门、成员的管理权限。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "deleted"
}

获取成员

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&amp;userid=lisi

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
userid 是 员工UserID。对应管理端的帐号
  • 返回结果
{
   "errcode": 0,
   "errmsg": "ok",
   "userid": "zhangsan",
   "name": "李四",
   "department": [1, 2],
   "position": "后台工程师",
   "mobile": "15913215421",
   "email": "[email protected]",
   "weixinid": "lisifordev",  
   "avatar": "https://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0",
   "status": 1,
   "extattr": {"attrs":[{"name":"爱好","value":"旅游"},{"name":"卡号","value":"1234567234"}]}
}
参数说明
errcode 返回码
errmsg 对返回码的文本描述内容
userid 员工UserID。对应管理端的帐号
name 成员名称
department 成员所属部门id列表
position 职位信息
mobile 手机号码
email 邮箱
weixinid 微信号
avatar 头像url。注：如果要获取小图将url最后的"/0"改成"/64"即可
status 关注状态: 1=已关注，2=已冻结，4=未关注
extattr 扩展属性
  • 权限说明
管理员须拥有’获取成员’的接口权限，以及成员的查看权限。

获取部门成员

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_token=ACCESS_TOKEN&amp;department_id=1&amp;fetch_child=0&amp;status=0

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
department_id 是 获取的部门id
fetch_child 否 1/0：是否递归获取子部门下面的成员
status 否 0获取全部员工，1获取已关注成员列表，2获取禁用成员列表，4获取未关注成员列表。status可叠加
  • 权限说明
管理员须拥有’获取部门成员’的接口权限，以及指定部门的查看权限。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "ok",
   "userlist": [
           {
                  "userid": "zhangsan",
                  "name": "李四"
           }
     ]
}
参数说明
errcode 返回码
errmsg 对返回码的文本描述内容
userlist 成员列表
userid 员工UserID。对应管理端的帐号
name 成员名称

获取部门成员(详情)

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/user/list?access_token=ACCESS_TOKEN&amp;department_id=1&amp;fetch_child=0&amp;status=0

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
department_id 是 获取的部门id
fetch_child 否 1/0：是否递归获取子部门下面的成员
status 否 0获取全部员工，1获取已关注成员列表，2获取禁用成员列表，4获取未关注成员列表。status可叠加
  • 权限说明
管理员须拥有’获取部门成员’的接口权限，以及指定部门的查看权限。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "ok",
   "userlist": [
           {
                  "userid": "zhangsan",
                  "name": "李四",
                  "department": [1, 2],
                  "position": "后台工程师",
                  "mobile": "15913215421",
                  "email": "[email protected]",
                  "weixinid": "lisifordev",  
                  "avatar":           "https://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0",
                  "status": 1,
                  "extattr": {"attrs":[{"name":"爱好","value":"旅游"},{"name":"卡号","value":"1234567234"}]}
           }
     ]
}
参数说明
errcode 返回码
errmsg 对返回码的文本描述内容
userlist 成员列表
userid 员工UserID。对应管理端的帐号
name 成员名称
department 成员所属部门id列表
position 职位信息
mobile 手机号码
email 邮箱
weixinid 微信号
avatar 头像url。注：如果要获取小图将url最后的"/0"改成"/64"即可
status 关注状态: 1=已关注，2=已冻结，4=未关注
extattr 扩展属性

邀请成员关注

  • 接口说明
认证号优先使用微信推送邀请关注，如果没有weixinid字段则依次对手机号，邮箱绑定的微信进行推送，全部没有匹配则通过邮件邀请关注。 邮箱字段无效则邀请失败。 非认证号只通过邮件邀请关注。邮箱字段无效则邀请失败。 已关注以及被禁用用户不允许发起邀请关注请求。
  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/invite/send?access_token=ACCESS_TOKEN

请求包结构体为:

{
   "userid":"xxxxx",
   "invite_tips":"xxx"

}

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
userid 是 用户的userid
invite_tips 否 推送到微信上的提示语（只有认证号可以使用）。当使用微信推送时，该字段默认为“请关注XXX企业号”，邮件邀请时，该字段无效。
  • 权限说明
管理员须拥有该成员的查看权限
  • 返回结果
{
   "errcode": 0,
   "errmsg": "ok",
   "type":1
}
参数说明
errcode 返回码
errmsg 对返回码的文本描述内容
type 1:微信邀请 2.邮件邀请

管理标签

## 目录
### **创建标签**
  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/create?access_token=ACCESS_TOKEN

请求包结构体为:

{
   "tagname": "UI"
}
  • 参数说明
参数必须说明
access_token 是 调用接口凭证
tagname 是 标签名称。长度为1~64个字符，标签不可与其他同组的标签重名，也不可与全局标签重名
  • 权限说明
创建的标签属于管理组;默认为未加锁状态。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "created"
   "tagid": "1"
}

更新标签名字

  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/update?access_token=ACCESS_TOKEN

请求包示例如下:

{
   "tagid": "1",
   "tagname": "UI design"
}
  • 参数说明
参数必须说明
access_token 是 调用接口凭证
tagid 是 标签ID
tagname 是 标签名称。长度为1~64个字符，标签不可与其他同组的标签重名，也不可与全局标签重名
  • 权限说明
管理组必须是指定标签的创建者。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "updated"
}

删除标签

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/tag/delete?access_token=ACCESS_TOKEN&amp;tagid=1

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
tagid 是 标签ID
  • 权限说明
管理组必须是指定标签的创建者，并且标签的成员列表为空。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "deleted"
}

获取标签成员

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/tag/get?access_token=ACCESS_TOKEN&amp;tagid=1

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
tagid 是 标签ID
  • 权限说明
管理组须拥有“获取标签成员”的接口权限，标签须对管理组可见；返回列表仅包含管理组管辖范围的成员。
  • 返回结果
{
   "errcode": 0,
   "errmsg": "ok",
   "userlist": [
         {
             "userid": "zhangsan",
             "name": "李四"
         }
     ],
   "partylist": [2]
}
参数说明
errcode 错误码
errmsg 错误消息
userlist 成员列表
userlist::userid 员工UserID
userlist::name 员工姓名
partylist 部门列表

增加标签成员

  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/addtagusers?access_token=ACCESS_TOKEN

请求包示例如下:

{
   "tagid": "1",
   "userlist":[ "user1","user2"],
   "partylist": [4]
}
  • 参数说明
参数必须说明
access_token 是 调用接口凭证
tagid 是 标签ID
userlist 否 企业员工ID列表，注意：userlist、partylist不能同时为空
partylist 否 企业部门ID列表，注意：userlist、partylist不能同时为空
  • 权限说明
标签对管理组可见且未加锁，成员属于管理组管辖范围。
  • 返回结果
a)正确时返回 
{
   "errcode": 0,
   "errmsg": "ok"
}
b)若部分userid、partylist非法，则返回 
{
   "errcode": 0,
   "errmsg": "错误消息",
   "invalidlist"："usr1|usr2|usr",
   "invalidparty"：[2,4]
}
其中错误消息视具体出错情况而定，分别为：
invalid userlist and partylist faild
invalid userlist faild
invalid partylist faild

c)当包含userid、partylist全部非法时返回

{
   "errcode": 40070,
   "errmsg": "all list invalid "
}
参数说明
errcode 错误码
errmsg 错误消息
invalidlist 不在权限内的员工ID列表，以“|”分隔
invalidparty 不在权限内的部门ID列表

删除标签成员

  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/tag/deltagusers?access_token=ACCESS_TOKEN

请求包如下

{
   "tagid": "1",
   "userlist":[ "user1","user2"],
   "partylist":[2,4]
}
  • 参数说明
参数必须说明
access_token 是 调用接口凭证
tagid 是 标签ID
userlist 否 企业员工ID列表，注意：userlist、partylist不能同时为空
partylist 否 企业部门ID列表，注意：userlist、partylist不能同时为空
  • 权限说明
标签对管理组可见且未加锁，成员属于管理组管辖范围。
  • 返回结果
a)正确时返回 
{
   "errcode": 0,
   "errmsg": "deleted"
}
b)若部分userid、partylist非法，则返回 
{
   "errcode": 0,
   "errmsg": "错误消息",
   "invalidlist"："usr1|usr2|usr",
   "invalidparty": [2,4]
}
其中错误消息视具体出错情况而定，分别为：
invalid userlist and partylist faild
invalid userlist faild
invalid partylist faild

c)当包含的userid、partylist全部非法时返回

{
   "errcode": 40031,
   "errmsg": "all list invalid"
}
参数说明
errcode 错误码
errmsg 错误消息
invalidlist 不在权限内的或者非法的员工ID列表，以“|”分隔
invalidparty 不在权限内的部门ID列表

获取标签列表

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/tag/list?access_token=ACCESS_TOKEN

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
  • 权限说明
标签对管理组可见
  • 返回结果
{
   "errcode": 0,
   "errmsg": "ok",
   "taglist":[
      {"tagid":1,"tagname":"a"},
      {"tagid":2,"tagname":"b"}
   ]
}
#　管理多媒体文件

企业在使用接口时，对多媒体文件、多媒体消息的获取和调用等操作，是通过media_id来进行的。通过本接口，企业可以上传或下载多媒体文件。

注意，每个多媒体文件（media_id）会在上传到微信服务器3天后自动删除，以节省服务器资源。

上传媒体文件

上传媒体文件

用于上传图片、语音、视频等媒体资源文件以及普通文件（如doc，ppt），接口返回媒体资源标识ID：media_id。请注意，media_id是可复用的，同一个media_id可用于消息的多次发送(5天内有效)。

  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&amp;type=TYPE

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
type 是 媒体文件类型，分别有图片（image）、语音（voice）、视频（video），普通文件(file)
media 是 form-data中媒体文件标识，有filename、filelength、content-type等信息
  • 权限说明
完全公开。所有管理员均可调用，media_id可以共享。
  • 返回说明
{
   "type": "image",
   "media_id": "0000001",
   "created_at": "1380000000"
}
参数说明
type 媒体文件类型，分别有图片（image）、语音（voice）、视频（video）,普通文件(file)
media_id 媒体文件上传后获取的唯一标识
created_at 媒体文件上传时间戳
  • 上传的媒体文件限制
图片（image）:1MB，支持JPG格式

语音（voice）：2MB，播放长度不超过60s，支持AMR格式

视频（video）：10MB，支持MP4格式

普通文件（file）：10MB

获取媒体文件

获取媒体文件

通过media_id获取图片、语音、视频等文件，协议和普通的http文件下载完全相同。

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&amp;media_id=MEDIA_ID

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
media_id 是 媒体文件id
  • 权限说明
完全公开。所有管理员均可调用，media_id可以共享。
  • 返回结果
和普通的http下载相同，请根据http头做相应的处理。

a)正确时返回：

{
   HTTP/1.1 200 OK
   Connection: close
   Content-Type: image/jpeg
   Content-disposition: attachment; filename="MEDIA_ID.jpg"
   Date: Sun, 06 Jan 2013 10:20:18 GMT
   Cache-Control: no-cache, must-revalidate
   Content-Length: 339721

   Xxxx
}

b)错误时返回（这里省略了HTTP首部）：

{
   "errcode": "40004",
   "errmsg": "invalid media_id"
}

接收消息与事件

将应用设置在回调模式时，企业可以通过回调URL接收员工回复的消息，以及员工关注、点击菜单、上报地理位置等事件。

在接收到事件后，企业可以发送被动响应消息，实现员工与企业的互动。

企业在接收消息，以及发送被动响应消息时，数据包以xml格式组成，以AES方式加密传输。具体可参考'建立连接'中的'回调模式'一节。

关注与取消关注

## 目录
## **关注与取消关注** 员工在关注企业号时，首先要与企业通讯录中的帐号绑定；如果企业开启了二次验证，那么在绑定成功后还需要经过企业的验证，才可以关注成功。

员工与通讯录中的帐号绑定

员工关注企业号时，会根据员工的微信号、微信绑定的手机或邮箱，与企业通讯录的帐号匹配。如果匹配到，则绑定成功；否则会下发一条图文消息给员工，引导员工在页面上验证手机号或邮箱，验证后即绑定成功。注意，员工的微信版本需要在5.4以上，目前仅支持iOS、Android两个平台。

二次验证

企业在开启二次验证时，必须填写企业二次验证页面的url。当员工绑定通讯录中的帐号后，会收到一条图文消息，引导员工到企业的验证页面验证身份。在跳转到企业的验证页面时，会带上如下参数：code=CODE&state=STATE，企业可以调用oauth2接口，根据code获取员工的userid。

企业在员工验证成功后，调用如下接口即可让员工关注成功。

  • 请求说明
Https请求方式: GET

https://qyapi.weixin.qq.com/cgi-bin/user/authsucc?access_token=ACCESS_TOKEN&amp;userid=USERID

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
userid 是 员工UserID
  • 权限说明
管理员须拥有userid对应员工的管理权限。
  • 返回结果
{
   "errcode": "0",
   "errmsg": "ok"
}

关注/取消关注事件的推送

员工关注、取消关注企业号的事件，会推送到每个应用在管理端设置的URL；特别的，默认企业小助手可以用于获取整个企业号的关注状况。（以下假设该URL为https://api.3dept.com）。

  • 请求说明
Http请求方式: POST

https://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS&amp;timestamp=13500001234&amp;nonce=123412323

  • 参数说明
<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[UserID]]></FromUserName>
   <CreateTime>1348831860</CreateTime>
   <MsgType><![CDATA[event]]></MsgType>
   <Event><![CDATA[subscribe]]></Event>
   <AgentID>1</AgentID>
</xml>
参数说明
ToUserName 企业号CorpID
FromUserName 员工UserID
CreateTime 消息创建时间 （整型）
MsgType 消息类型，此时固定为：event
Event 事件类型，subscribe(订阅)、unsubscribe(取消订阅)
AgentID 企业应用的id，整型。可在应用的设置页面获取；如果id为0，则表示是整个企业号的关注/取消关注事件

接受普通信息

## 目录
## **接收普通消息** 普通消息是指员工向企业号应用发送的消息，包括文本、图片、语音、视频、地理位置等类型。普通消息会推送到每个应用在管理端设置的URL（以下假设该URL为https://api.3dept.com）。
  • 请求说明
Http请求方式: POST

https://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS&amp;timestamp=13500001234&amp;nonce=123412323

text消息

<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>1348831860</CreateTime>
   <MsgType><![CDATA[text]]></MsgType>
   <Content><![CDATA[this is a test]]></Content>
   <MsgId>1234567890123456</MsgId>
   <AgentID>1</AgentID>
</xml>
参数说明
ToUserName 企业号CorpID
FromUserName 员工UserID
CreateTime 消息创建时间（整型）
MsgType 消息类型，此时固定为：text
Content 文本消息内容
MsgId 消息id，64位整型
AgentID 企业应用的id，整型。可在应用的设置页面查看

image消息

<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>1348831860</CreateTime>
   <MsgType><![CDATA[image]]></MsgType>
   <PicUrl><![CDATA[this is a url]]></PicUrl>
   <MediaId><![CDATA[media_id]]></MediaId>
   <MsgId>1234567890123456</MsgId>
   <AgentID>1</AgentID>
</xml>
参数说明
ToUserName 企业号CorpID
FromUserName 员工UserID
CreateTime 消息创建时间（整型）
MsgType 消息类型，此时固定为：image
PicUrl 图片链接
MediaId 图片媒体文件id，可以调用获取媒体文件接口拉取数据
MsgId 消息id，64位整型
AgentID 企业应用的id，整型。可在应用的设置页面查看

voice消息

<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>1357290913</CreateTime>
   <MsgType><![CDATA[voice]]></MsgType>
   <MediaId><![CDATA[media_id]]></MediaId>
   <Format><![CDATA[Format]]></Format>
   <MsgId>1234567890123456</MsgId>
   <AgentID>1</AgentID>
</xml>
参数说明
ToUserName 企业号CorpID
FromUserName 员工UserID
CreateTime 消息创建时间（整型）
MsgType 消息类型，此时固定为：voice
MediaId 语音媒体文件id，可以调用获取媒体文件接口拉取数据
Format 语音格式，如amr，speex等
MsgId 消息id，64位整型
AgentID 企业应用的id，整型。可在应用的设置页面查看

video消息

<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>1357290913</CreateTime>
   <MsgType><![CDATA[video]]></MsgType>
   <MediaId><![CDATA[media_id]]></MediaId>
   <ThumbMediaId><![CDATA[thumb_media_id]]></ThumbMediaId>
   <MsgId>1234567890123456</MsgId>
   <AgentID>1</AgentID>
</xml>
参数说明
ToUserName 企业号CorpID
FromUserName 员工UserID
CreateTime 消息创建时间（整型）
MsgType 消息类型，此时固定为：video
MediaId 视频媒体文件id，可以调用获取媒体文件接口拉取数据
ThumbMediaId 视频消息缩略图的媒体id，可以调用获取媒体文件接口拉取数据
MsgId 消息id，64位整型
AgentID 企业应用的id，整型。可在应用的设置页面查看

location消息

<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>1351776360</CreateTime>
   <MsgType><![CDATA[location]]></MsgType>
   <Location_X>23.134521</Location_X>
   <Location_Y>113.358803</Location_Y>
   <Scale>20</Scale>
   <Label><![CDATA[位置信息]]></Label>
   <MsgId>1234567890123456</MsgId>
   <AgentID>1</AgentID>
</xml>
参数说明
ToUserName 企业号CorpID
FromUserName 员工UserID
CreateTime 消息创建时间（整型）
MsgType 消息类型，此时固定为：location
Location_X 地理位置纬度
Location_Y 地理位置经度
Scale 地图缩放大小
Label 地理位置信息
MsgId 消息id，64位整型
AgentID 企业应用的id，整型。可在应用的设置页面查看

接收事件

## 目录
## **接收事件** 事件是指员工在企业号上的某些操作行为，比如关注、上报地理位置、点击菜单等。（关注事件请参考’关注与取消关注’）。事件会推送到每个应用在管理端设置的URL（以下假设该URL为https://api.3dept.com）。
  • 请求说明
Http请求方式: POST

https://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS&amp;timestamp=13500001234&amp;nonce=123412323

上报地理位置事件

员工同意上报地理位置后，每次在进入应用会话时都会上报一次地理位置，或在进入应用会话后每5秒上报一次地理位置。企业可以在管理端修改应用的以上设置。上报地理位置时，微信会将此事件推送到企业应用在管理端设置的URL（以下假设该URL为https://api.3dept.com）。

  • 请求说明
Http请求方式: POST

https://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS&amp;timestamp=13500001234&amp;nonce=123412323

  • 参数说明
<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[FromUser]]></FromUserName>
   <CreateTime>123456789</CreateTime>
   <MsgType><![CDATA[event]]></MsgType>
   <Event><![CDATA[LOCATION]]></Event>
   <Latitude>23.104105</Latitude>
   <Longitude>113.320107</Longitude>
   <Precision>65.000000</Precision>
   <AgentID>1</AgentID>
</xml>
参数说明
ToUserName 企业号CorpID
FromUserName 员工UserID
CreateTime 消息创建时间（整型）
MsgType 消息类型，此时固定为：event
Event 事件类型，此时固定为：LOCATION
Latitude 地理位置纬度
Longitude 地理位置经度
Precision 地理位置精度
AgentID 企业应用的id，整型。可在应用的设置页面查看

上报菜单事件

用户点击自定义菜单后，微信会把点击事件推送给开发者，请注意，点击菜单弹出子菜单，不会产生上报。另外，扫码、拍照及地理位置的菜单事件，仅支持微信iPhone5.4.1/Android5.4以上版本，旧版本微信用户点击后将没有回应，开发者也不能正常接收到事件推送。

**点击菜单拉取消息的事件推送**

推送XML数据包示例： 
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[CLICK]]></Event>
<EventKey><![CDATA[EVENTKEY]]></EventKey>
<AgentID>1</AgentID>
</xml>
参数说明：
参数 描述
ToUserName 微信企业号
FromUserName 员工UserID
CreateTime 消息创建时间 （整型）
MsgType 消息类型，event
Event 事件类型，CLICK
EventKey 事件KEY值，与自定义菜单接口中KEY值对应
AgentID 应用代理ID

**点击菜单跳转链接的事件推送**

推送XML数据包示例： 
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[VIEW]]></Event>
<EventKey><![CDATA[www.qq.com]]></EventKey>
<AgentID>1</AgentID>
</xml>
参数说明：
参数 描述
ToUserName 微信企业号
FromUserName 员工UserID
CreateTime 消息创建时间 （整型）
MsgType 消息类型，event
Event 事件类型，VIEW
EventKey 事件KEY值，设置的跳转URL
AgentID 应用代理ID

**扫码推事件的事件推送**

推送XML数据包示例： 
<xml><ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>1408090502</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[scancode_push]]></Event>
<EventKey><![CDATA[6]]></EventKey>
<ScanCodeInfo><ScanType><![CDATA[qrcode]]></ScanType>
<ScanResult><![CDATA[1]]></ScanResult>
</ScanCodeInfo>
<AgentID>1</AgentID>
</xml>
参数说明：
参数 描述
ToUserName 微信企业号
FromUserName 员工UserID
CreateTime 消息创建时间（整型）
MsgType 消息类型，event
Event 事件类型，scancode_push
EventKey 事件KEY值，由开发者在创建菜单时设定
ScanCodeInfo 扫描信息
ScanType 扫描类型，一般是qrcode
ScanResult 扫描结果，即二维码对应的字符串信息
AgentID 应用代理ID

**扫码推事件且弹出“消息接收中”提示框的事件推送**

推送XML数据包示例： 
<xml><ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>1408090606</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[scancode_waitmsg]]></Event>
<EventKey><![CDATA[6]]></EventKey>
<ScanCodeInfo><ScanType><![CDATA[qrcode]]></ScanType>
<ScanResult><![CDATA[2]]></ScanResult>
</ScanCodeInfo>
<AgentID>1</AgentID>
</xml>
参数说明：
参数 描述
ToUserName 微信企业号
FromUserName 员工UserID
CreateTime 消息创建时间 （整型）
MsgType 消息类型，event
Event 事件类型，scancode_waitmsg
EventKey 事件KEY值，由开发者在创建菜单时设定
ScanCodeInfo 扫描信息
ScanType 扫描类型，一般是qrcode
ScanResult 扫描结果，即二维码对应的字符串信息
AgentID 应用代理ID

**弹出系统拍照发图的事件推送**

推送XML数据包示例： 
<xml><ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>1408090651</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[pic_sysphoto]]></Event>
<EventKey><![CDATA[6]]></EventKey>
<SendPicsInfo><Count>1</Count>
<PicList><item><PicMd5Sum><![CDATA[1b5f7c23b5bf75682a53e7b6d163e185]]></PicMd5Sum>
</item>
</PicList>
</SendPicsInfo>
<AgentID>1</AgentID>
</xml>
参数说明：
参数 描述
ToUserName 微信企业号
FromUserName 员工UserID
CreateTime 消息创建时间 （整型）
MsgType 消息类型，event
Event 事件类型，pic_sysphoto
EventKey 事件KEY值，由开发者在创建菜单时设定
SendPicsInfo 发送的图片信息
Count 发送的图片数量
PicList 图片列表
PicMd5Sum 图片的MD5值，开发者若需要，可用于验证接收到图片
AgentID 应用代理ID

**弹出拍照或者相册发图的事件推送**

推送XML数据包示例： 
<xml><ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>1408090816</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[pic_photo_or_album]]></Event>
<EventKey><![CDATA[6]]></EventKey>
<SendPicsInfo><Count>1</Count>
<PicList><item><PicMd5Sum><![CDATA[5a75aaca956d97be686719218f275c6b]]></PicMd5Sum>
</item>
</PicList>
</SendPicsInfo>
<AgentID>1</AgentID>
</xml>
参数说明：
参数 描述
ToUserName 微信企业号
FromUserName 员工UserID
CreateTime 消息创建时间 （整型）
MsgType 消息类型，event
Event 事件类型，pic_photo_or_album
EventKey 事件KEY值，由开发者在创建菜单时设定
SendPicsInfo 发送的图片信息
Count 发送的图片数量
PicList 图片列表
PicMd5Sum 图片的MD5值，开发者若需要，可用于验证接收到图片
AgentID 应用代理ID

**弹出微信相册发图器的事件推送**

推送XML数据包示例： 
<xml><ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>1408090816</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[pic_weixin]]></Event>
<EventKey><![CDATA[6]]></EventKey>
<SendPicsInfo><Count>1</Count>
<PicList><item><PicMd5Sum><![CDATA[5a75aaca956d97be686719218f275c6b]]></PicMd5Sum>
</item>
</PicList>
</SendPicsInfo>
<AgentID>1</AgentID>
</xml>
参数说明：
参数 描述
ToUserName 微信企业号
FromUserName 员工UserID
CreateTime 消息创建时间 （整型）
MsgType 消息类型，event
Event 事件类型，pic_weixin
EventKey 事件KEY值，由开发者在创建菜单时设定
SendPicsInfo 发送的图片信息
Count 发送的图片数量
PicList 图片列表
PicMd5Sum 图片的MD5值，开发者若需要，可用于验证接收到图片
AgentID 应用代理ID

**弹出地理位置选择器的事件推送**

推送XML数据包示例： 
<xml><ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>1408091189</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[location_select]]></Event>
<EventKey><![CDATA[6]]></EventKey>
<SendLocationInfo><Location_X><![CDATA[23]]></Location_X>
<Location_Y><![CDATA[113]]></Location_Y>
<Scale><![CDATA[15]]></Scale>
<Label><![CDATA[ 广州市海珠区客村艺苑路 106号]]></Label>
<Poiname><![CDATA[]]></Poiname>
</SendLocationInfo>
<AgentID>1</AgentID>
</xml>
参数说明：
参数 描述
ToUserName 微信企业号
FromUserName 员工UserID
CreateTime 消息创建时间 （整型）
MsgType 消息类型，event
Event 事件类型，location_select
EventKey 事件KEY值，由开发者在创建菜单时设定
SendLocationInfo 发送的位置信息
Location_X X坐标信息
Location_Y Y坐标信息
Scale 精度，可理解为精度或者比例尺、越精细的话 scale越高
Label 地理位置的字符串信息
Poiname 朋友圈POI的名字，可能为空
AgentID 应用代理ID

**用户进入应用的事件推送**

本事件只有在应用的回调模式中打开上报开关时上报 推送XML数据包示例： 
<xml><ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>1408091189</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[enter_agent]]></Event>
<EventKey><![CDATA[]]></EventKey>
<AgentID>1</AgentID>
</xml>
参数说明：
参数 描述
ToUserName 微信企业号
FromUserName 员工UserID
CreateTime 消息创建时间 （整型）
MsgType 消息类型，event
Event 事件类型，enter_agent
EventKey 事件KEY值，此事件该值为空
 ## 被动响应信息
## 目录
## **被动响应消息** **企业响应的消息同样应该经过加密，并带上msg_signature、timestamp、nonce及密文**，其中timestamp、nonce由企业指定，msg_signature、密文经特定算法生成，具体算法参见附录。

以下是标准的回包：

<xml>
   <Encrypt><![CDATA[msg_encrypt]]></Encrypt>
   <MsgSignature><![CDATA[msg_signature]]></MsgSignature>
   <TimeStamp>timestamp</TimeStamp>
   <Nonce><![CDATA[nonce]]></Nonce>
</xml>

以下是各类型消息的明文XML结构：

text消息

<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>1348831860</CreateTime>
   <MsgType><![CDATA[text]]></MsgType>
   <Content><![CDATA[this is a test]]></Content>
</xml>
参数说明
ToUserName 员工UserID
FromUserName 企业号CorpID
CreateTime 消息创建时间（整型）
MsgType 消息类型，此时固定为：text
Content 文本消息内容

image消息

<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>1348831860</CreateTime>
   <MsgType><![CDATA[image]]></MsgType>
   <Image>
       <MediaId><![CDATA[media_id]]></MediaId>
   </Image>
</xml>
参数说明
ToUserName 员工UserID
FromUserName 企业号CorpID
CreateTime 消息创建时间（整型）
MsgType 消息类型，此时固定为：image
MediaId 图片文件id，可以调用上传媒体文件接口获取

voice消息

<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>1357290913</CreateTime>
   <MsgType><![CDATA[voice]]></MsgType>
   <Voice>
       <MediaId><![CDATA[media_id]]></MediaId>
   </Voice>
</xml>
参数说明
ToUserName 员工UserID
FromUserName 企业号CorpID
CreateTime 消息创建时间（整型）
MsgType 消息类型，此时固定为：voice
MediaId 语音文件id，可以调用上传媒体文件接口获取

video消息

<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>1357290913</CreateTime>
   <MsgType><![CDATA[video]]></MsgType>
   <Video>
       <MediaId><![CDATA[media_id]]></MediaId>
       <Title><![CDATA[title]]></Title>
       <Description><![CDATA[description]]></Description>
   </Video>
</xml>
参数说明
ToUserName 员工UserID
FromUserName 企业号CorpID
CreateTime 消息创建时间（整型）
MsgType 消息类型，此时固定为：video
MediaId 视频文件id，可以调用上传媒体文件接口获取
Title 视频消息的标题
Description 视频消息的描述

news消息

<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>12345678</CreateTime>
   <MsgType><![CDATA[news]]></MsgType>
   <ArticleCount>2</ArticleCount>
   <Articles>
       <item>
           <Title><![CDATA[title1]]></Title>
           <Description><![CDATA[description1]]></Description>
           <PicUrl><![CDATA[picurl]]></PicUrl>
           <Url><![CDATA[url]]></Url>
       </item>
       <item>
           <Title><![CDATA[title]]></Title>
           <Description><![CDATA[description]]></Description>
           <PicUrl><![CDATA[picurl]]></PicUrl>
           <Url><![CDATA[url]]></Url>
       </item>
   </Articles>
</xml>
参数说明
ToUserName 员工UserID
FromUserName 企业号CorpID
CreateTime 消息创建时间（整型）
MsgType 消息类型，此时固定为：news
ArticleCount 图文条数，默认第一条为大图。图文数不能超过10，否则将会无响应
Title 图文消息标题
Description 图文消息描述
PicUrl 图片链接，支持JPG、PNG格式，较好的效果为大图360*200，小图200*200
Url 点击图文消息跳转链接

发送消息

企业可以主动发消息给员工，消息量不受限制。

调用接口时，使用Https协议、JSON数据包格式，数据包不需做加密处理。

目前支持文本、图片、语音、视频、文件、图文等消息类型。除了news类型，其它类型的消息可在发送时加上保密选项，保密消息会被打上水印，并且只有接收者才能阅读。

发送接口说明

发送接口说明

  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
  • 权限要求
需要管理员对应用有使用权限，对收件人touser、toparty、totag有查看权限，否则本次调用失败。
  • 返回结果
如果对应用或收件人、部门、标签任何一个无权限，则本次发送失败；如果收件人、部门或标签不存在，发送仍然执行，但返回无效的部分。 
{
   "errcode": 0,
   "errmsg": "ok",
   "invaliduser": "UserID1",
   "invalidparty":"PartyID1",
   "invalidtag":"TagID1"
}

消息类型及数据结构

## 目录
### **text消息** 
{
   "touser": "UserID1|UserID2|UserID3",
   "toparty": " PartyID1 | PartyID2 ",
   "totag": " TagID1 | TagID2 ",
   "msgtype": "text",
   "agentid": "1",
   "text": {
       "content": "Holiday Request For Pony(https://xxxxx)"
   },
   "safe":"0"
}
参数 必须说明
touser 否 UserID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送
toparty 否 PartyID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
totag 否 TagID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
msgtype 是 消息类型，此时固定为：text
agentid 是 企业应用的id，整型。可在应用的设置页面查看
content 是 消息内容
safe 否 表示是否是保密消息，0表示否，1表示是，默认0

image消息

{
   "touser": "UserID1|UserID2|UserID3",
   "toparty": " PartyID1 | PartyID2 ",
   "msgtype": "image",
   "agentid": "1",
   "image": {
       "media_id": "MEDIA_ID"
   },
   "safe":"0"
}
参数 必须说明
touser 否 UserID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送
toparty 否 PartyID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
totag 否 TagID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
msgtype 是 消息类型，此时固定为：image
agentid 是 企业应用的id，整型。可在应用的设置页面查看
media_id 是 图片媒体文件id，可以调用上传媒体文件接口获取
safe 否 表示是否是保密消息，0表示否，1表示是，默认0

voice消息

{
   "touser": "UserID1|UserID2|UserID3",
   "toparty": " PartyID1 | PartyID2 ",
   "totag": " TagID1 | TagID2 ",
   "msgtype": "voice",
   "agentid": "1",
   "voice": {
       "media_id": "MEDIA_ID"
   },
   "safe":"0"
}
参数 必须说明
touser 否 UserID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送
toparty 否 PartyID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
totag 否 TagID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
msgtype 是 消息类型，此时固定为：voice
agentid 是 企业应用的id，整型。可在应用的设置页面查看
media_id 是 语音文件id，可以调用上传媒体文件接口获取
safe 否 表示是否是保密消息，0表示否，1表示是，默认0

video消息

{
   "touser": "UserID1|UserID2|UserID3",
   "toparty": " PartyID1 | PartyID2 ",
   "totag": " TagID1 | TagID2 ",
   "msgtype": "video",
   "agentid": "1",
   "video": {
       "media_id": "MEDIA_ID",
       "title": "Title",
       "description": "Description"
   },
   "safe":"0"
}
参数 必须说明
touser 否 UserID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送
toparty 否 PartyID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
totag 否 TagID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
msgtype 是 消息类型，此时固定为：video
agentid 是 企业应用的id，整型。可在应用的设置页面查看
media_id 是 视频媒体文件id，可以调用上传媒体文件接口获取
title 否 视频消息的标题
description 否 视频消息的描述
safe 否 表示是否是保密消息，0表示否，1表示是，默认0

file消息

{
   "touser": "UserID1|UserID2|UserID3",
   "toparty": " PartyID1 | PartyID2 ",
   "totag": " TagID1 | TagID2 ",
   "msgtype": "file",
   "agentid": "1",
   "file": {
       "media_id": "MEDIA_ID"
   },
   "safe":"0"
}
参数 必须说明
touser 否 UserID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送
toparty 否 PartyID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
totag 否 TagID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
msgtype 是 消息类型，此时固定为：file
agentid 是 企业应用的id，整型。可在应用的设置页面查看
media_id 是 媒体文件id，可以调用上传媒体文件接口获取
safe 否 表示是否是保密消息，0表示否，1表示是，默认0

news消息

{
   "touser": "UserID1|UserID2|UserID3",
   "toparty": " PartyID1 | PartyID2 ",
   "totag": " TagID1 | TagID2 ",
   "msgtype": "news",
   "agentid": "1",
   "news": {
       "articles":[
           {
               "title": "Title",
               "description": "Description",
               "url": "URL",
               "picurl": "PIC_URL"
           },
           {
               "title": "Title",
               "description": "Description",
               "url": "URL",
               "picurl": "PIC_URL"
           }
       ]
   }
}
参数 必须说明
touser 否 UserID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送
toparty 否 PartyID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
totag 否 TagID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
msgtype 是 消息类型，此时固定为：news
agentid 是 企业应用的id，整型。可在应用的设置页面查看
articles 是 图文消息，一个图文消息支持1到10条图文
title 否 标题
description 否 描述
url 否 点击后跳转的链接。企业可根据url里面带的code参数校验员工的真实身份。具体参考“9 微信页面跳转员工身份查询”
picurl 否 图文消息的图片链接，支持JPG、PNG格式，较好的效果为大图640*320，小图80*80。如不填，在客户端不显示图片

mpnews消息

注：mpnews消息与news消息类似，不同的是图文消息内容存储在微信后台，并且支持保密选项。

{
   "touser": "UserID1|UserID2|UserID3",
   "toparty": " PartyID1 | PartyID2 ",
   "totag": " TagID1 | TagID2 ",
   "msgtype": "mpnews",
   "agentid": "1",
   "mpnews": {
       "articles":[
           {
               "title": "Title",
               "thumb_media_id": "id",
               "author": "Author",
               "content_source_url": "URL",
               "content": "Content",
               "digest": "Digest description",
               "show_cover_pic": "0"
           },
           {
               "title": "Title",
               "thumb_media_id": "id",
               "author": "Author",
               "content_source_url": "URL",
               "content": "Content",
               "digest": "Digest description",
               "show_cover_pic": "0"
           }
       ]
   }
   "safe":"0"
}
参数 必须说明
touser 否 UserID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向关注该企业应用的全部成员发送
toparty 否 PartyID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
totag 否 TagID列表，多个接受者用‘|’分隔。当touser为@all时忽略本参数
msgtype 是 消息类型，此时固定为：mpnews
agentid 是 企业应用的id，整型。可在应用的设置页面查看
articles 是 图文消息，一个图文消息支持1到10个图文
title 是 图文消息的标题
thumb_media_id 是 图文消息缩略图的media_id, 可以在上传多媒体文件接口中获得。此处thumb_media_id即上传接口返回的media_id
author 否 图文消息的作者
content_source_url 否 图文消息点击“阅读原文”之后的页面链接
content 是 图文消息的内容，支持html标签
digest 否 图文消息的描述
show_cover_pic 否 是否显示封面，1为显示，0为不显示
safe 否 表示是否是保密消息，0表示否，1表示是，默认0

自定义菜单

企业号的每个应用都可以拥有自己的菜单，企业可以调用接口来创建、删除、获取应用菜单。

注意，在操作应用的菜单时，应用必须处于回调模式；菜单最多为两级，一级菜单最多为3个，二级菜单最多为5个。

创建应用菜单

创建应用菜单

目前自定义菜单最多包括3个一级菜单，每个一级菜单最多包含5个二级菜单。一级菜单最多4个汉字，二级菜单最多7个汉字，多出来的部分将会以“...”代替。请注意，创建自定义菜单后，由于微信客户端缓存，需要24小时微信客户端才会展现出来。建议测试时可以尝试取消关注企业号后再次关注，则可以看到创建后的效果。
自定义菜单接口可实现多种类型按钮，如下：

字段值 功能名称说明
click 点击推事件 用户点击click类型按钮后，微信服务器会通过消息接口推送消息类型为event 的结构给开发者（参考消息接口指南），并且带上按钮中开发者填写的key值，开发者可以通过自定义的key值与用户进行交互；
view 跳转URL 用户点击view类型按钮后，微信客户端将会打开开发者在按钮中填写的网页URL，可与网页授权获取用户基本信息接口结合，获得用户基本信息。
scancode_push 扫码推事件 用户点击按钮后，微信客户端将调起扫一扫工具，完成扫码操作后显示扫描结果（如果是URL，将进入URL），且会将扫码的结果传给开发者，开发者可以下发消息。
scancode_waitmsg 扫码推事件且弹出“消息接收中”提示框 用户点击按钮后，微信客户端将调起扫一扫工具，完成扫码操作后，将扫码的结果传给开发者，同时收起扫一扫工具，然后弹出“消息接收中”提示框，随后可能会收到开发者下发的消息。
pic_sysphoto 弹出系统拍照发图 用户点击按钮后，微信客户端将调起系统相机，完成拍照操作后，会将拍摄的相片发送给开发者，并推送事件给开发者，同时收起系统相机，随后可能会收到开发者下发的消息。
pic_photo_or_album 弹出拍照或者相册发图 用户点击按钮后，微信客户端将弹出选择器供用户选择“拍照”或者“从手机相册选择”。用户选择后即走其他两种流程。
pic_weixin 弹出微信相册发图器 用户点击按钮后，微信客户端将调起微信相册，完成选择操作后，将选择的相片发送给开发者的服务器，并推送事件给开发者，同时收起相册，随后可能会收到开发者下发的消息。
location_select 弹出地理位置选择器用户点击按钮后，微信客户端将调起地理位置选择工具，完成选择操作后，将选择的地理位置发送给开发者的服务器，同时收起位置选择工具，随后可能会收到开发者下发的消息。
**请注意，除click和view外所有事件，仅支持微信iPhone5.4.1/Android5.4以上版本，旧版本微信用户点击后将没有回应，开发者也不能正常接收到事件推送。**
  • 请求说明
Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN&amp;agentid=1

click和view类型请求包如下：

{
   "button":[
       {
           "type":"click",
           "name":"今日歌曲",
           "key":"V1001_TODAY_MUSIC"
       },
       {
           "name":"菜单",
           "sub_button":[
               {
                   "type":"view",
                   "name":"搜索",
                   "url":"https://www.soso.com/"
               },
               {
                   "type":"click",
                   "name":"赞一下我们",
                   "key":"V1001_GOOD"
               }
           ]
      }
   ]
}

其他新增按钮类型的请求示例

{
    "button": [
        {
            "name": "扫码",
            "sub_button": [
                {
                    "type": "scancode_waitmsg",
                    "name": "扫码带提示",
                    "key": "rselfmenu_0_0",
                    "sub_button": [ ]
                },
                {
                    "type": "scancode_push",
                    "name": "扫码推事件",
                    "key": "rselfmenu_0_1",
                    "sub_button": [ ]
                }
            ]
        },
        {
            "name": "发图",
            "sub_button": [
                {
                    "type": "pic_sysphoto",
                    "name": "系统拍照发图",
                    "key": "rselfmenu_1_0",
                   "sub_button": [ ]
                 },
                {
                    "type": "pic_photo_or_album",
                    "name": "拍照或者相册发图",
                    "key": "rselfmenu_1_1",
                    "sub_button": [ ]
                },
                {
                    "type": "pic_weixin",
                    "name": "微信相册发图",
                    "key": "rselfmenu_1_2",
                    "sub_button": [ ]
                }
            ]
        },
        {
            "name": "发送位置",
            "type": "location_select",
            "key": "rselfmenu_2_0"
        }
    ]
}
  • 参数说明
参数必须说明
access_token 是 调用接口凭证
agentid 是 企业应用的id，整型。可在应用的设置页面查看
button 是 一级菜单数组，个数应为1~3个
sub_button 否 二级菜单数组，个数应为1~5个
type 是 菜单的响应动作类型
name 是 菜单标题，不超过16个字节，子菜单不超过40个字节
key click等点击类型必须 菜单KEY值，用于消息接口推送，不超过128字节
url view类型必须 网页链接，员工点击菜单可打开链接，不超过256字节
  • 权限说明
管理员须拥有应用的管理权限，并且应用必须设置在回调模式。

返回结果

{
   "errcode":0,
   "errmsg":"ok"
}

删除菜单

  • 请求说明
Https请求方式：GET

https://qyapi.weixin.qq.com/cgi-bin/menu/delete?access_token=ACCESS_TOKEN&amp;agentid=1

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
agentid 是 企业应用的id，整型。可在应用的设置页面查看
  • 权限说明
管理员须拥有应用的管理权限，并且应用必须设置在回调模式。
  • 返回结果
{
   "errcode":0,
   "errmsg":"ok"
}

获取菜单列表

  • 请求说明
Https请求方式：GET

https://qyapi.weixin.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN&amp;agentid=1

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
agentid 是 企业应用的id，整型。可在应用的设置页面查看
  • 权限说明
管理员须拥有应用的管理权限，并且应用必须设置在回调模式。
  • 返回结果
返回结果与菜单创建的参数一致。

OAuth2验证接口

企业应用中的URL链接（包括自定义菜单或者消息中的链接），可以通过OAuth2.0验证接口来获取员工的身份信息。

通过此接口获取用户身份会有一定的时间开销。对于频繁获取用户身份的场景，建议采用如下方案：

1、企业应用中的URL链接直接填写企业自己的页面地址

2、用户跳转到企业页面时，企业校验是否有代表用户身份的cookie，此cookie由企业生成

3、如果没有获取到cookie，重定向到OAuth验证链接，获取用户身份后，由企业生成代表用户身份的cookie

4、根据cookie获取用户身份，进入相应的页面

注意，此URL的域名，必须完全匹配企业应用设置项中的'可信域名'，否则获取用户信息时会返回50001错误码。

企业获取code

企业获取code

企业如果需要员工在跳转到企业网页时带上员工的身份信息，需构造如下的链接：

https://open.weixin.qq.com/connect/oauth2/authorize?appid=CORPID&amp;redirect_uri=REDIRECT_URI&amp;response_type=code&amp;scope=SCOPE&amp;state=STATE#wechat_redirect

  • 参数说明
参数必须说明
appid 是 企业的CorpID
redirect_uri 是 授权后重定向的回调链接地址，请使用urlencode对链接进行处理
response_type 是 返回类型，此时固定为：code
scope 是 应用授权作用域，此时固定为：snsapi_base
state 否 重定向后会带上state参数，企业可以填写a-zA-Z0-9的参数值
#wechat_redirect 是 微信终端使用此参数判断是否需要带上身份信息
 员工点击后，页面将跳转至 redirect_uri/?code=CODE&state=STATE，企业可根据code参数获得员工的userid。

根据Code获取成员信息

  • 请求说明
Https请求方式：GET

https://qyapi.weixin.qq.com/cgi-bin/user/getuserinfo?access_token=ACCESS_TOKEN&amp;code=CODE&amp;agentid=AGENTID

  • 参数说明
参数必须说明
access_token 是 调用接口凭证
code 是 通过员工授权获取到的code，每次员工授权带上的code将不一样，code只能使用一次，5分钟未被使用自动过期
agentid 是 跳转链接时所在的企业应用ID
  • 权限说明
管理员须拥有agent的使用权限；agentid必须和跳转链接时所在的企业应用ID相同。
  • 返回结果
a)正确时返回示例如下： 
{
   "UserId":"USERID",
   "DeviceId":"DEVICEID"
}
参数说明
UserId 员工UserID
DeviceId 手机设备号(由微信在安装时随机生成)
 出错时返回示例如下： 
{
   "errcode": "40029",
   "errmsg": "invalid code"
}

微信JS接口

微信JS-SDK说明文档
## 目录
## 概述 微信JS-SDK是微信公众平台面向网页开发者提供的基于微信内的网页开发工具包。 通过使用微信JS-SDK，网页开发者可借助微信高效地使用拍照、选图、语音、位置等手机系统的能力，同时可以直接使用微信分享、扫一扫等微信特有的能力，为微信用户提供更优质的网页体验。 此文档面向网页开发者介绍微信JS-SDK如何使用及相关注意事项。 ### 使用说明 在使用微信JS-SDK对应的JS接口前，需确保已获得使用对应JS接口的权限，可在下表中根据自己的帐号角色查看。 企业号帐号角色分为体验号、注册号和认证号，其中体验号与注册号的权限一致，认证号则拥有更多的JS-SDK权限，具体详见下方表格：
功能 接口 注册号和体验号 认证号
基础接口 判断当前客户端版本是否支持指定JS接口 有 有
分享接口 获取“分享到朋友圈”按钮点击状态及设置分享内容接口 无 有
获取“分享给朋友”按钮点击状态及设置分享内容接口 无 有
获取“分享到QQ”按钮点击状态及设置分享内容接口 无 有
获取“分享到腾讯微博”按钮点击状态及设置分享内容接 无 有
图像接口 本地选图或拍照接口 有 有
图片预览接口 有 有
上传图片接口 有 有
下载图片接口 有 有
音频接口 开始录音接口 有 有
停止录音接口 有 有
播放音频接口 有 有
暂停播放接口 有 有
停止播放接口 有 有
上传语音接口 有 有
下载语音接口 有 有
智能接口 识别音频并返回识别结果接口 有 有
设备信息 获取网络状态接口 有 有
地理位置 查看地理位置地图接口 有 有
获取地理位置接口 有 有
地理位置 隐藏右上角菜单接口 有 有
显示右上角菜单接口 有 有
关闭当前窗口接口 有 有
批量隐藏菜单项接口 有 有
批量显示菜单项接口 有 有
隐藏所有非基本菜单项接口 有 有
显示所有被隐藏的非基本菜单项接口 有 有
微信扫一扫 扫一扫接口 有 有
 注意： 所有的JS接口只能在企业号应用的可信域名下调用，可在企业号应用中心里设置应用可信域名。

步骤一：引入JS文件

在需要调用JS接口的页面引入如下JS文件，（支持https）：https://res.wx.qq.com/open/js/jweixin-1.0.0.js 备注：支持使用 AMD/CMD 标准模块加载方法加载

步骤二：通过config接口注入权限验证配置

所有需要使用JS-SDK的页面必须先注入配置信息，否则将无法调用（同一个url仅需调用一次，对于变化url的SPA的web app可在每次url变化时进行调用）。 
wx.config({
    debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。
    appId: '', // 必填，企业号的唯一标识，此处填写企业号corpid
    timestamp: , // 必填，生成签名的时间戳
    nonceStr: '', // 必填，生成签名的随机串
    signature: '',// 必填，签名，见附录1
    jsApiList: [] // 必填，需要使用的JS接口列表，所有JS接口列表见附录2
});

步骤三：通过ready接口处理成功验证

wx.ready(function(){
    // config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异步操作，所以如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中。
});

步骤四：通过error接口处理失败验证

wx.error(function(res){
    // config信息验证失败会执行error函数，如签名过期导致验证失败，具体错误信息可以打开config的debug模式查看，也可以在返回的res参数中查看，对于SPA可以在这里更新签名。
});
### 接口调用说明 所有接口通过wx对象(也可使用jWeixin对象)来调用，参数是一个对象，除了每个接口本身需要传的参数之外，还有以下通用参数：
  1. success：接口调用成功时执行的回调函数。
  2. fail：接口调用失败时执行的回调函数。
  3. complete：接口调用完成时执行的回调函数，无论成功或失败都会执行。
  4. cancel：用户点击取消时的回调函数，仅部分有用户取消操作的api才会用到。
  5. trigger: 监听Menu中的按钮点击时触发的方法，该方法仅支持Menu中的相关接口。

以上几个函数都带有一个参数，类型为对象，其中除了每个接口本身返回的数据之外，还有一个通用属性errMsg，其值格式如下：
  1. 调用成功时："xxx:ok" ，其中xxx为调用的接口名
  2. 用户取消时："xxx:cancel"，其中xxx为调用的接口名
  3. 调用失败时：其值为具体错误信息
## 基础接口 ### 判断当前客户端版本是否支持指定JS接口 
wx.checkJsApi({
    jsApiList: ['chooseImage'] // 需要检测的JS接口列表，所有JS接口列表见附录2,
    success: function(res) {
        // 以键值对的形式返回，可用的api值true，不可用为false
        // 如：{"checkResult":{"chooseImage":true},"errMsg":"checkJsApi:ok"}
    });
备注：checkJsApi接口是客户端6.0.2新引入的一个预留接口，第一期开放的接口均可不使用checkJsApi来检测。 ## 分享接口 请注意不要有诱导分享等违规行为，对于诱导分享行为将永久回收企业号接口权限，详细规则请查看：朋友圈管理常见问题 。 ### 获取“分享到朋友圈”按钮点击状态及自定义分享内容接口 
wx.onMenuShareTimeline({
    title: '', // 分享标题
    link: '', // 分享链接
    imgUrl: '', // 分享图标
    success: function () {
        // 用户确认分享后执行的回调函数
    },
    cancel: function () {
        // 用户取消分享后执行的回调函数
    }
});
### 获取“分享给朋友”按钮点击状态及自定义分享内容接口 
wx.onMenuShareAppMessage({
    title: '', // 分享标题
    desc: '', // 分享描述
    link: '', // 分享链接
    imgUrl: '', // 分享图标
    type: '', // 分享类型,music、video或link，不填默认为link
    dataUrl: '', // 如果type是music或video，则要提供数据链接，默认为空
    success: function () {
        // 用户确认分享后执行的回调函数
    },
    cancel: function () {
        // 用户取消分享后执行的回调函数
    }
});
### 获取“分享到QQ”按钮点击状态及自定义分享内容接口 
wx.onMenuShareQQ({
    title: '', // 分享标题
    desc: '', // 分享描述
    link: '', // 分享链接
    imgUrl: '' // 分享图标
    success: function () {
       // 用户确认分享后执行的回调函数
    },
    cancel: function () {
       // 用户取消分享后执行的回调函数
    }
});
### 获取“分享到腾讯微博”按钮点击状态及自定义分享内容接口 
wx.onMenuShareWeibo({
    title: '', // 分享标题
    desc: '', // 分享描述
    link: '', // 分享链接
    imgUrl: '' // 分享图标
    success: function () {
       // 用户确认分享后执行的回调函数
    },
    cancel: function () {
        // 用户取消分享后执行的回调函数
    }
});
## 图像接口 ### 拍照或从手机相册中选图接口 
wx.chooseImage({
    success: function (res) {
        var localIds = res.localIds; // 返回选定照片的本地ID列表，localId可以作为img标签的src属性显示图片
    }
});
### 预览图片接口 
wx.previewImage({
    current: '', // 当前显示的图片链接
    urls: [] // 需要预览的图片链接列表
});
### 上传图片接口 
wx.uploadImage({
    localId: '', // 需要上传的图片的本地ID，由chooseImage接口获得
    isShowProgressTips: 1// 默认为1，显示进度提示
    success: function (res) {
        var serverId = res.serverId; // 返回图片的服务器端ID
    }
});
备注：可用企业微信获取媒体文件接口下载上传的语音，此处获得的 serverId 即 media_id，参考文档 https://qydev.weixin.qq.com/wiki/index.php?title=%E8%8E%B7%E5%8F%96%E5%AA%92%E4%BD%93%E6%96%87%E4%BB%B6

下载图片接口

wx.downloadImage({
    serverId: '', // 需要下载的图片的服务器端ID，由uploadImage接口获得
    isShowProgressTips: 1// 默认为1，显示进度提示
    success: function (res) {
        var localId = res.localId; // 返回图片下载后的本地ID
    }
});

音频接口

开始录音接口

wx.startRecord();

停止录音接口

wx.stopRecord({
    success: function (res) {
        var localId = res.localId;
    }
});

监听录音自动停止接口

wx.onVoiceRecordEnd({
    // 录音时间超过一分钟没有停止的时候会执行 complete 回调
    complete: function (res) {
        var localId = res.localId;
    }
});

播放语音接口

wx.playVoice({
    localId: '' // 需要播放的音频的本地ID，由stopRecord接口获得
});

暂停播放接口

wx.pauseVoice({
    localId: '' // 需要暂停的音频的本地ID，由stopRecord接口获得
});

停止播放接口

wx.stopVoice({
    localId: '' // 需要停止的音频的本地ID，由stopRecord接口获得
});

监听语音播放完毕接口

wx.onVoicePlayEnd({
    serverId: '', // 需要下载的音频的服务器端ID，由uploadVoice接口获得
    success: function (res) {
        var localId = res.localId; // 返回音频的本地ID
    }
});

上传语音接口

wx.uploadVoice({
    localId: '', // 需要上传的音频的本地ID，由stopRecord接口获得
    isShowProgressTips: 1// 默认为1，显示进度提示
        success: function (res) {
        var serverId = res.serverId; // 返回音频的服务器端ID
    }
});

备注：可用企业微信获取媒体文件接口下载上传的语音，此处获得的 serverId 即 media_id，参考文档 https://qydev.weixin.qq.com/wiki/index.php?title=%E8%8E%B7%E5%8F%96%E5%AA%92%E4%BD%93%E6%96%87%E4%BB%B6

下载语音接口

wx.downloadVoice({
    serverId: '', // 需要下载的音频的服务器端ID，由uploadVoice接口获得
    isShowProgressTips: 1// 默认为1，显示进度提示
    success: function (res) {
        var localId = res.localId; // 返回音频的本地ID
    }
});

智能接口

识别音频并返回识别结果接口

wx.translateVoice({
   localId: '', // 需要识别的音频的本地Id，由录音相关接口获得
    isShowProgressTips: 1, // 默认为1，显示进度提示
    success: function (res) {
        alert(res.translateResult); // 语音识别的结果
    }
});

设备信息

获取网络状态接口

wx.getNetworkType({
    success: function (res) {
        var networkType = res.networkType; // 返回网络类型2g，3g，4g，wifi
    }
});

地理位置

使用微信内置地图查看位置接口

wx.openLocation({
    latitude: 0, // 纬度，浮点数，范围为90 ~ -90
    longitude: 0, // 经度，浮点数，范围为180 ~ -180。
    name: '', // 位置名
    address: '', // 地址详情说明
    scale: 1, // 地图缩放级别,整形值,范围从1~28。默认为最大
    infoUrl: '' // 在查看位置界面底部显示的超链接,可点击跳转
});

获取地理位置接口

wx.getLocation({
    timestamp: 0, // 位置签名时间戳，仅当需要兼容6.0.2版本之前时提供
    nonceStr: '', // 位置签名随机串，仅当需要兼容6.0.2版本之前时提供
    addrSign: '', // 位置签名，仅当需要兼容6.0.2版本之前时提供，详见附录4
    success: function (res) {
       var longitude = res.longitude; // 纬度，浮点数，范围为90 ~ -90
       var latitude = res.latitude; // 经度，浮点数，范围为180 ~ -180。
        var speed = res.speed; // 速度，以米/每秒计
        var accuracy = res.accuracy; // 位置精度
    }
});

界面操作

隐藏右上角菜单接口

wx.hideOptionMenu();

显示右上角菜单接口

wx.showOptionMenu();

关闭当前网页窗口接口

wx.closeWindow();

批量隐藏功能按钮接口

wx.hideMenuItems({
    menuList: [] // 要隐藏的菜单项，所有menu项见附录3
});

批量显示功能按钮接口

wx.showMenuItems({
    menuList: [] // 要显示的菜单项，所有menu项见附录3
});

隐藏所有非基础按钮接口

wx.hideAllNonBaseMenuItem();

显示所有功能按钮接口

wx.showAllNonBaseMenuItem();

微信扫一扫

调起微信扫一扫接口

wx.scanQRCode({
    desc: 'scanQRCode desc',
    needResult: 0, // 默认为0，扫描结果由微信处理，1则直接返回扫描结果，
    scanType: ["qrCode","barCode"], // 可以指定扫二维码还是一维码，默认二者都有
    success: function (res) {
    var result = res.resultStr; // 当needResult 为 1 时，扫码返回的结果
}
});

附录1-JS-SDK使用权限签名算法

jsapi_ticket 生成签名之前必须先了解一下jsapi_ticket，jsapi_ticket是企业号用于调用微信JS接口的临时票据。正常情况下，jsapi_ticket的有效期为7200秒，通过access_token来获取。由于获取jsapi_ticket的api调用次数非常有限，频繁刷新jsapi_ticket会导致api调用受限，影响自身业务，开发者必须在自己的服务全局缓存jsapi_ticket 。

  1. 参考以下文档获取access_token（有效期7200秒，开发者必须在自己的服务全局缓存access_token）：https://qydev.weixin.qq.com/wiki/index.php?title=%E4%B8%BB%E5%8A%A8%E8%B0%83%E7%94%A8
  2. 用第一步拿到的access_token 采用http GET方式请求获得jsapi_ticket（有效期7200秒，开发者必须在自己的服务全局缓存jsapi_ticket）：https://qyapi.weixin.qq.com/cgi-bin/get_jsapi_ticket?access_token=ACCESS_TOKEN

成功返回如下JSON： 
{
"errcode":0,
"errmsg":"ok",
"ticket":"bxLdikRXVbTPdHSM05e5u5sUoXNKd8-41ZO3MhKoyN5OfkWITDGgnr2fwJ0m9E8NYzWKVZvdVtaUgWvsdshFKA",
"expires_in":7200
}
获得jsapi_ticket之后，就可以生成JS-SDK权限验证的签名了。

签名算法 签名生成规则如下：参与签名的字段包括noncestr（随机字符串）, 有效的jsapi_ticket, timestamp（时间戳）, url（当前网页的URL，不包含#及其后面部分） 。对所有待签名参数按照字段名的ASCII 码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1。这里需要注意的是所有参数名均为小写字符。对string1作sha1加密，字段名和字段值都采用原始值，不进行URL 转义。
即signature=sha1(string1)。 示例：

  • noncestr=Wm3WZYTPz0wzccnW
  • jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg
  • timestamp=1414587457
  • url=https://qy.weixin.qq.com

步骤1. 对所有待签名参数按照字段名的ASCII 码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1： 
jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg&noncestr=Wm3WZYTPz0wzccnW&timestamp=1414587457&url=https://qy.weixin.qq.com

步骤2. 对string1进行sha1签名，得到signature： 
e9b72681621e836c6babbceafc7f5df0be59932d
注意事项
  1. 签名用的noncestr和timestamp必须与wx.config中的nonceStr和timestamp相同。
  2. 签名用的url必须是调用JS接口页面的完整URL。
  3. 出于安全考虑，开发者必须在服务器端实现签名的逻辑。

附录2-所有JS接口列表

版本1.0.0接口

  • onMenuShareTimeline
  • onMenuShareAppMessage
  • onMenuShareQQ
  • onMenuShareWeibo
  • startRecord
  • stopRecord
  • onVoiceRecordEnd
  • playVoice
  • pauseVoice
  • stopVoice
  • onVoicePlayEnd
  • uploadVoice
  • downloadVoice
  • chooseImage
  • previewImage
  • uploadImage
  • downloadImage
  • translateVoice
  • getNetworkType
  • openLocation
  • getLocation
  • hideOptionMenu
  • showOptionMenu
  • hideMenuItems
  • showMenuItems
  • hideAllNonBaseMenuItem
  • showAllNonBaseMenuItem
  • closeWindow
  • scanQRCode
## 附录3-所有菜单项列表 基本类
  • 举报: "menuItem:exposeArticle"
  • 调整字体: "menuItem:setFont"
  • 日间模式: "menuItem:dayMode"
  • 夜间模式: "menuItem:nightMode"
  • 刷新: "menuItem:refresh"
  • 查看企业号（已添加）: "menuItem:profile"
  • 查看企业号（未添加）: "menuItem:addContact"
传播类
  • 发送给朋友: "menuItem:share:appMessage"
  • 分享到朋友圈: "menuItem:share:timeline"
  • 分享到QQ: "menuItem:share:qq"
  • 分享到Weibo: "menuItem:share:weiboApp"
  • 收藏: "menuItem:favorite"
  • 分享到FB: "menuItem:share:facebook"
保护类
  • 调试: "menuItem:jsDebug"
  • 编辑标签: "menuItem:editTag"
  • 删除: "menuItem:delete"
  • 复制链接: "menuItem:copyUrl"
  • 原网页: "menuItem:originPage"
  • 阅读模式: "menuItem:readMode"
  • 在QQ浏览器中打开: "menuItem:openWithQQBrowser"
  • 在Safari中打开: "menuItem:openWithSafari"
  • 邮件: "menuItem:share:email"
  • 一些特殊企业号: "menuItem:share:brand"

附录4-位置签名生成算法

addrSign的生成规则与JS-SDK权限验证的签名生成规则相同（参考附录1），只是参与签名参数有所不同。参与addrSign的签名参数有：corpid、url（当前网页url）、timestamp、noncestr、accesstoken（用户授权凭证，请参照oauth2.0 协议获取）。

附录5-常见错误及解决方法

调用config 接口的时候传入参数 debug: true 可以开启debug模式，页面会alert出错误信息。以下为常见错误及解决方法：

  1. invalid url domain当前页面所在域名与使用的corpid没有绑定（可在该企业号的应用可信域名中配置域名）。
  2. invalid signature签名错误。建议按如下顺序检查：
    1. 确认签名算法正确，可用 https://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=jsapisign 页面工具进行校验。
    2. 确认config中noncestr, timestamp与用以签名中的对应noncestr, timestamp一致。
    3. 确认url是页面完整的url，包括GET参数部分。
    4. 确认 config 中的 corpid 与用来获取 jsapi_ticket 的 corpid 一致。
  3. the permission value is offline verifying这个错误是因为config没有正确执行，或者是调用的JSAPI没有传入config的jsApiList参数中。建议按如下顺序检查：
    1. 确认config正确通过。
    2. 如果是在页面加载好时就调用了JSAPI，则必须写在wx.ready的回调中。
    3. 确认config的jsApiList参数包含了这个JSAPI。
  4. permission denied该应用没有权限使用这个JSAPI。
## 附录5-DEMO页面和示例代码 DEMO页面： https://demo.open.weixin.qq.com/jssdk
Jssdk demo001.png

示例代码： https://demo.open.weixin.qq.com/jssdk/sample.zip 备注：链接中包含php、java、nodejs以及python的示例代码供第三方参考，第三方切记要对获取的accesstoken以及jsapi_ticket进行缓存以确保不会触发频率限制。 ## 附录6-问题反馈 邮箱地址：[email protected] 邮件主题：【微信JS-SDK反馈】 邮件内容说明： 用简明的语言描述问题所在，并交代清楚遇到该问题的场景，可附上截屏图片，微信团队会尽快处理你的反馈。 # 第三方应用授权 ## **目的与场景**

目前，企业号管理员要通过繁琐的操作才能与第三方应用提供商对接。通过第三方授权接口，能够减少企业号管理员的操作步骤，提升第三方应用的接入效率。

第三方应用授权方案包含以下两个场景：

一）应用提供商注册应用

你，作为应用提供商若要使用此方案，只需在企业号官网的开发者中心注册成为第三方应用提供商，创建应用套件，并在应用套件中配置好相应的应用。然后在你的官网发布应用套件，以便于企业号管理员访问即可。

另外，你必须具备以下几个条件：

1、拥有通过认证的，能证明第三方应用提供商身份的企业号。

2、具有互联网上部署及发布你的应用的能力。

本方案所说的应用套件，是第三方应用授权的主体，它可以包含多个第三方所提供的同一类型的应用。目前一个第三方最多可以注册五个应用套件，一个应用套件最多可以包含十五个应用。

二）企业号管理员授权应用

企业号的管理员浏览你的官网，发现适合他的应用套件后，即可发起一键授权，系统将展示企业号第三方授权页面，管理员根据授权页面的引导，确认授权内容，完成授权操作。

授权完成之后，企业号就可使用应用提供商所提供的应用服务了。一切将变得简单自然。以下章节将对每一个操作过程做具体的介绍和说明。

应用提供注册应用

注册成为第三方应用提供商

注册成为应用提供商，必须输入以下信息：

信息项要求及说明
企业Logo 应用提供商的企业Logo，小于2M，640*240，背景为白色
企业简称 使用对外宣传的企业简称，能代表企业的名字，2-16个字
企业简介 描述企业所提供的服务，4-120个字
企业官网 应用服务商的企业官网
 注册条件：a）拥有一个已经过认证的企业号 b）用系统管理员身份进行申请

创建应用套件

开发者完成注册之后，即可创建应用套件。应用套件是第三方应用授权的主体，接口的开发都与应用套件息息相关，请开发者仔细阅读下方内容。

基本信息：

信息项要求及说明
套件Logo 应用套件的Logo，小于2M，640*240，在授权页会被用于展示。
介绍网站 介绍该应用套件网站或者页面
应用套件介绍 描述该应用套件所提供的服务，4-120个字
服务行业 该应用套件所服务的行业对象，一个套件只能属于一个服务行业。
套件标签 套件提供的服务类型，如OA办公、CRM、HR、ERP等。一个套件只能拥有一个标签。
 **注意：**

1）你应谨慎选择所填写的服务行业，后续的版本中，用户可以在企业号中通过服务行业搜索相应的套件。

2）你可以创建或者选择其他开发者已创建的标签。你应该谨慎选择套件标签，用户往往会在企业号中通过标签查找相关联的套件。

开发信息：

套件参数内容说明
发起授权域名 在该域名下发起的授权请求才可被通过，企业点击授权链接时，企业号会检查该域名是否已登记。
授权完成回调域名 在第三方应用授权流程中，授权成功后会回调该域名，返回临时code。你需用此code换取永久授权码，请尽量将此域名与发起授权域名保持一致。
服务事件接收URL 系统将会把此套件的授权变更事件以及ticket参数推送给此URL。(ticket说明详见API接口说明)
Token 可任意填写，用于生成签名,校验回调请求的合法性。
EncodingAESKey 回调消息加解密参数，是AES密钥的Base64编码，用于解密回调消息内容对应的密文。
白名单IP列表 应用套件调用企业号第三方应用API时的合法IP列表，只有白名单内的IP才能正常调用企业号API，后续IP若有修改，需要及时进行列表更新。
特殊权限 是否需要通讯录管理权限，需要应用提供商在注册套件时进行申报。若勾选通讯录管理权限，在授权页会出现相应需要授权内容。如果应用不会修改企业通讯录的内容，则无需勾选。
 创建完成之后，系统会告知开发者该应用套件的Suiteid和Suitesecret。（详见第三方应用接口说明）

在应用套件里添加应用

当你创建完应用套件后，需要在套件配置应用，应用的信息填写相对简单。

基本信息：

信息项要求及说明
应用Logo 应用的Logo，小于2M，640*240，在授权页会被用于展示。
应用名称 应用的名称，2-16个字。
功能介绍 描述该应用的功能与特色，4-120个字内
 **开发信息：**
应用参数内容说明
callbackurl 用于接收托管企业号应用的用户消息，URL支持使用$CORPID$模板参数表示corpid，推送事件时会替换为企业的corpid。
特殊权限 应用的特殊权限为上报地理位置的功能开关，若在创建应用时勾选了此特殊权限，在授权会提示用户。
 ## 企业号管理员授权应用 ### **应用提供商网站发起授权** 应用提供商构造授权链接，该链接中需要提供套件suieid、预授权码和服务事件接收的url，预授权码通过接口get_preauthcode获取（详见第三方应用接口说明）。

同时，为了保证授权体验的一致性，企业号也提供了统一的授权按钮样式，开发者可在（设计资源下载）中找到。

企业号系统管理员点击授权链接进入授权页，此时会校验授权链接所在的域名是否已被登记。

展示授权页面，选择授权内容

由于应用套件里有多个应用，管理员需要选择第三方提供的应用与企业号内的应用进行关联，且企业号内的一个应用只能授权给一个第三方应用提供商。

若该应用套件在注册时申报了需要通讯录管理权限，此时在授权页会提示企业管理员，并让管理员选择部门标签或者成员进行授权。

完成授权操作

企业管理员完成授权之后，页面会回跳第三方应用提供商的网站（即应用套件的授权完成回调域名），此时会带上一个临时code，开发者使用临时code通过接口query_auth换取永久授权码。（详见第三方应用接口说明）

授权完成后，授权方的企业号管理后台在权限管理里会出现第三方管理组类型，系统管理员也可进行取消授权操作与修改通讯录授权内容，企业取消授权与授权内容的改变也会实时通知应用提供商。

应用提供商在授权成功之后，会得到权限情况如下表所示：

授权主体 权限内容 权限情况
应用套件 应用 应用头像 读写
应用简介 读写
地理位置上报开关 读写（应用创建时申报）
可信域名 读写
用户状态变更 读写
应用id 只读
应用可见范围 只读
使用应用发消息、自定义菜单、oAuth 2.0等接口 读写
通讯录 授权的通讯录（包括成员、部门、标签） 读写
 ## 第三方应用接口说明
## 目录
## **第三方应用接口说明**

接口概述

应用提供商拥有自己的API集合，主要用于完成授权流程以及实现授权后的相关功能。 套件API（即接口）如下：

功能API名称
获取应用套件令牌 get_suite_token
获取预授权码 get_pre_auth_code
获取企业号的永久授权码 get_permanent_code
获取企业号应用 get_agent
设置企业号应用 set_agent
获取企业号access_token get_corp_token
获取企业授权信息 get_auth_info
 应用套件在获得企业号授权后，应用提供商可以获取企业号access_token，调用企业授权给应用套件的API，企业号API的使用方式详见

https://qydev.weixin.qq.com/wiki/index.php?title=%E9%A6%96%E9%A1%B5

特别注意，所有API调用需要验证来源IP。只有在应用套件申请信息中填写的合法IP列表内才能合法调用，其他一律拒绝。

授权流程说明

Sqlc1.png

下面对其进行详细介绍：

1）企业进入应用提供商网站

指的是，企业系统管理员进入应用提供商网站，如www.ABC.com。

2）获取预授权码

预授权码是应用套件实现授权托管的安全凭证，通过suite_id，suite_secret和suite_ticket获取，相关接口为get_pre_auth_code。

3）应用提供商引导企业系统管理员进入应用套件授权页

应用提供商可以在自己的网站中放置“微信企业号应用授权”的入口，引导企业号管理员进入应用套件授权页。网址为:

https://qy.weixin.qq.com/cgi-bin/loginpage?suite_id=$suite_id$&amp;pre_auth_code=$pre_auth_code$&amp;redirect_uri=$redirect_uri$&amp;state=$state$

该网址中应用提供商需要提供suite_id、预授权码、授权完成回调URI和state

4）企业号管理员确认并同意授权托管给应用提供商

企业号管理员进入套件授权页后，设置授权内容，确认并同意将自己的企业号应用或通讯录授权托管给应用提供商，完成授权流程。

5）授权成功，返回临时授权码

授权流程完成后，会进入回调URI，并在URI参数中返回授权码、过期时间以及state参数(redirect_uri?auth_code=xxx&expires_in=1200&state=xx)

6）利用临时授权码获取永久授权码以及授权信息

在得到临时授权码后，应用提供商可以使用临时授权码换取永久授权码以及授权信息，后续可以通过永久授权码调用企业号相关API（能调用哪些API，取决于用户将哪些权限集授权给了应用提供商）。

获取应用套件令牌

该API用于获取应用套件令牌（suite_access_token）。

**注1：**由于应用提供商可能托管了大量的企业号，其安全问题造成的影响会更加严重，故API中除了合法来源IP校验之外，还额外增加了1项安全策略：

获取suite_access_token时，还额外需要suite_ticket参数**（请永远使用最新接收到的suite_ticket）**。suite_ticket由企业号后台定时推送给应用套件，并定时更新。

**注2：**通过本接口获取的accesstoken不会自动续期，每次获取都会自动更新。

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/get_suite_token

POST数据示例

{
    "suite_id":"id_value" ,
    "suite_secret": "secret_value",
    "suite_ticket": "ticket_value"
}

请求参数说明

参数说明
suite_id 应用套件id
suite_secret 应用套件secret
suite_ticket 微信后台推送的ticket
 **返回结果示例** 
{
    "suite_access_token":"61W3mEpU66027wgNZ_MhGHNQDHnFATkDa9-2llqrMBjUwxRSNPbVsMmyD-yq8wZETSoE5NQgecigDrSHkPtIYA",
    "expires_in":7200
}

结果参数说明

参数说明
suite_access_token 应用套件access_token
expires_in 有效期

获取预授权码

该API用于获取预授权码。预授权码用于企业号授权时的应用提供商安全验证。

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/get_pre_auth_code?suite_access_token=xxx

POST数据示例

{
    "suite_id":"id_value",
    "appid":[id1,id2,id3]
}

请求参数说明

参数说明
suite_id 应用套件id
appid 应用id，本参数选填，表示用户能对本套件内的哪些应用授权，不填时默认用户有全部授权权限
 **返回结果示例** 
{
    "errcode":"0" ,
    "errmsg":"ok" ,
    "pre_auth_code":"Cx_Dk6qiBE0Dmx4EmlT3oRfArPvwSQ-oa3NL_fwHM7VI08r52wazoZX2Rhpz1dEw",
    "expires_in":1200
}
**结果参数说明**
参数说明
pre_auth_code 预授权码
expires_in 有效期

获取企业号的永久授权码

该API用于使用临时授权码换取授权方的永久授权码，并换取授权信息、企业access_token。

注：临时授权码使用一次后即失效

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/get_permanent_code?suite_access_token=xxxx

POST数据示例

{
    "suite_id":"id_value" ,
    "auth_code": "auth_code_value"
}

请求参数说明

参数说明
suite_id 应用套件id
auth_code 临时授权码会在授权成功时附加在redirect_uri中跳转回应用提供商网站。
 **返回结果示例** 
{
    "access_token": "xxxxxx",
    "expires_in": 7200,
    "permanent_code": "xxxx",
    "auth_corp_info":
    {
        "corpid": "xxxx",
        "corp_name": "name",
        "corp_type": "verified",
        "corp_round_logo_url": "xxxxxx",
        "corp_square_logo_url": "yyyyy",
        "corp_user_max": "50",
        "corp_agent_max": "30"
    },
    "auth_info":
    {
    "agent" :
        [
            {
                "agentid":"1",
                "name":"NAME",
                "square_logo_url":"xxxxxx",
                "round_logo_url":"yyyyyy",
                "appid":"1",
                "api_group":["get_location"]
            },
            {
                "agentid":"2",
                "name":"NAME2",
                "square_logo_url":"xxxxxx",
                "round_logo_url":"yyyyyy",
                "appid":"5",
                "api_group":[]
            }
        ],
        "department":
        [
            {
                "id":"2",
                "name":"PARTYNAME",
                "parentid":"1",
                "writable":"true"
            }
        ]
    }
}

结果参数说明

参数说明
access_token 授权方（企业）access_token
expires_in 授权方（企业）access_token超时时间
permanent_code 企业号永久授权码
corp_info 授权方企业信息
corpid 授权方企业号id
corp_name 授权方企业号名称
corp_type 授权方企业号类型，认证号：verified, 注册号：unverified，体验号：test
corp_round_logo_url 授权方企业号圆形头像
corp_square_logo_url 授权方企业号方形头像
corp_user_max 授权方企业号用户规模
corp_agent_max 授权方企业号应用规模
auth_info 授权信息
agent 授权的应用信息
agentid 授权方应用id
agent:name 授权方应用名字
square_logo_url 授权方应用方形头像
round_logo_url 授权方应用圆形头像
appid 服务商套件中的对应应用id
api_group 授权方应用敏感权限组，目前仅有get_location，表示是否有权限设置应用获取地理位置的开关
department 授权的通讯录部门
department:id 部门id
department:name 部门名称
department:parentid 父部门id
department:writable 是否具有该部门的写权限

获取企业号的授权信息

该API用于通过永久授权码换取企业号的授权信息。 永久code的获取，是通过临时授权码使用get_permanent_code 接口获取到的permanent_code。

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/get_auth_info?suite_access_token=xxxx

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/get_auth_info?suite_access_token=xxxx

POST数据示例

{
    "suite_id":"suite_id_value",
    "auth_corpid": "auth_corpid_value",
    "permanent_code": "code_value"
}

请求参数说明

参数说明
suite_id 应用套件id
auth_corpid 授权方corpid
permanent_code 永久授权码，通过get_permanent_code获取
 **返回结果示例** 
{
    "auth_corp_info": {
        "corpid": "xxxx",
        "corp_name": "name",
        "corp_type": "verified",
        "corp_round_logo_url": "xxxxxx",
        "corp_square_logo_url": "yyyyy",
        "corp_user_max": "50",
        "corp_agent_max": "30"
    },
    "auth_info": {
        "agent" : [
        {
            "agentid":"1",
            "name":"NAME",
            "round_logo_url":"xxxxxx",
            "square_logo_url ":"yyyyyy",
            "app_id":"1",
            "api_group":["get_location"]
        },
        {
            "agentid":"2",
            "name":"NAME2",
            "round_logo_url":"xxxxxx",
            "square_logo_url ":"yyyyyy",
            "app_id":"5",
            "api_group":[]
        }
        ],
        "department":[
        {
            "id":"2",
            "name":"PARTYNAME",
            "parentid":"1",
            "writable":"true"
        }
        ]
    }
}
**结果参数说明**
参数说明
auth_corp_info 授权方企业信息
corpid 授权方企业号id
corp_name 授权方企业号名称
corp_type 授权方企业号类型，认证号：verified, 注册号：unverified，体验号：test
corp_round_logo_url 授权方企业号圆形头像
corp_square_logo_url 授权方企业号方形头像
corp_user_max 授权方企业号用户规模
corp_agent_max 授权方企业号应用规模
auth_info 授权信息
agent 授权的应用信息
agentid 授权方应用id
agent:name 授权方应用名字
square_logo_url 授权方应用方形头像
round_logo_url 授权方应用圆形头像
appid 服务商套件中的对应应用id
api_group 授权方应用敏感权限组，目前仅有get_location，表示是否有权限设置应用获取地理位置的开关
department 授权的通讯录部门
department:id 部门id
department:name 部门名称
department:parentid 父部门id
department:writable 是否具有该部门的写权限

获取企业号应用

该API用于获取授权方的企业号某个应用的基本信息，包括头像、昵称、帐号类型、认证类型、可见范围等信息

接口调用请求说明

https请求方式: POST

<a rel="" class="external free" href="https://qyapi.weixin.qq.com/cgi-bin/service/get_agent?suite_access_token=xxxx">https://qyapi.weixin.qq.com/cgi-bin/service/get_agent?suite_access_token=xxxx</a>

POST数据示例

<pre>{
    "suit_id":"suit_id_value" ,
    "auth_corpid": "auth_corpid_value",
    "permanent_code": " permanent_code _value",
    "agentid ": "1"
}
</pre>
**请求参数说明**
<table border="1" cellspacing="0" cellpadding="4" align="center" width="640px">
<tbody><tr>
<th style="width:240px">参数</th><th>说明</th></tr>
<tr><td> suite_id</td><td> 应用套件id</td></tr>
<tr><td> auth_corpid</td><td> 授权方corpid</td></tr>
<tr><td> permanent_code</td><td> 永久授权码，从get_permanent_code接口中获取</td></tr>
<tr><td> agentid</td><td> 授权方应用id</td></tr></tbody></table>
**返回结果示例**
<pre>{
    "errcode":"0" ,
    "errmsg":"ok" ,
    "agentid":"1" ,
    "name":"NAME" ,
    "square_logo_url":"xxxxxxxx" ,
    "round_logo_url":"yyyyyyyy" ,
    "description":"desc" ,
    "allow_userinfos":{
        "user":[
            {
                "userid":"id1",
                "status":"1"
            },
            {
                "userid":"id2",
                "status":"1"
            },
            {
                "userid":"id3",
                "status":"1"
            }
        ]
    },
    "allow_partys": {
        "partyid": [1]
    }
    "allow_tags": {
        "tagid": [1,2,3]
    }
    "close":0 ,
    "redirect_domain":"www.qq.com",
    "report_location_flag":0,
    "isreportuser":0
}
</pre>

结果参数说明

<table border="1" cellspacing="0" cellpadding="4" align="center" width="640px">
<tbody><tr>
<th style="width:240px">参数</th><th>说明</th></tr>
<tr><td> agentid</td><td> 授权方企业应用id</td></tr>
<tr><td> name</td><td> 授权方企业应用名称</td></tr>
<tr><td> square_logo_url</td><td> 授权方企业应用方形头像</td></tr>
<tr><td> round_logo_url</td><td> 授权方企业应用圆形头像</td></tr>
<tr><td> description</td><td> 授权方企业应用详情</td></tr>
<tr><td> allow_userinfos</td><td> 授权方企业应用可见范围（人员），其中包括userid和关注状态state</td></tr>
<tr><td> allow_partys</td><td> 授权方企业应用可见范围（部门）</td></tr>
<tr><td> allow_tags</td><td> 授权方企业应用可见范围（标签）</td></tr>
<tr><td> close</td><td> 授权方企业应用是否被禁用</td></tr>
<tr><td> redirect_domain</td><td> 授权方企业应用可信域名</td></tr>
<tr><td> report_location_flag</td><td> 授权方企业应用是否打开地理位置上报  0：不上报；1：进入会话上报；2：持续上报</td></tr>
<tr><td> isreportuser</td><td> 是否接收用户变更通知。0：不接收；1：接收</td></tr></tbody></table>

设置企业号应用

该API用于设置授权方的企业应用的选项设置信息，如：地理位置上报等。注意，获取各项选项设置信息，需要有授权方的授权。

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/set_agent?suite_access_token=xxxx

POST数据示例

{
    "suite_id":"id_value",
    "auth_corpid": "auth_corpid_value",
    "permanent_code ": "code_value",
    "agent":
    {
        "agentid": "5",
        "report_location_flag": "0",
        "logo_mediaid": "xxxxx",
        "name": "NAME",
        "description": "DESC",
        "redirect_domain": "xxxxxx",
        "isreportuser":0
    }
}

请求参数说明

参数说明
suite_id 应用套件id
auth_corpid 授权方corpid
permanent_code 永久授权码，从get_permanent_code接口中获取
agent 要设置的企业应用的信息
agentid 企业应用的id
report_location_flag 企业应用是否打开地理位置上报 0：不上报；1：进入会话上报；2：持续上报
logo_mediaid 企业应用头像的mediaid，通过多媒体接口上传图片获得mediaid，上传后会自动裁剪成方形和圆形两个头像
name 企业应用名称
description 企业应用详情
redirect_domain 企业应用可信域名
isreportuser 是否接收用户变更通知。0：不接收；1：接收
 **返回结果示例** 
{
    "errcode":"0",
    "errmsg":"ok"
}

获取企业号access_token

应用提供商在取得企业号的永久授权码并完成对企业号应用的设置之后，便可以开始通过调用企业接口（详见企业接口文档）来运营这些应用。其中，调用企业接口所需的access_token获取方法如下。

接口调用请求说明

https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/service/get_corp_token?suite_access_token=xxxx

POST数据示例

{
    "suite_id":"suite_id_value",
    "auth_corpid": "auth_corpid_value",
    "permanent_code": "code_value"
}

请求参数说明

参数说明
suite_id 应用套件id
auth_corpid 授权方corpid
permanent_code 永久授权码，通过get_permanent_code获取
 **返回结果示例** 
{
    "access_token": "xxxxxx",
    "expires_in": 7200,
}

结果参数说明

参数说明
access_token 授权方（企业）access_token
expires_in 授权方（企业）access_token超时时间
 ## 第三方回调协议 ### **推送suite_ticket协议** 微信服务器会向应用提供商申请时填写的套件事件接收 URL定时推送ticket：

https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&amp;timestamp=1403610513&amp;nonce=380320359

POST数据示例

{
    <xml>
        <SuiteId><![CDATA[wxfc918a2d200c9a4c]]></SuiteId>
        <InfoType> <![CDATA[suite_ticket]]></InfoType>
        <TimeStamp>1403610513</TimeStamp>
        <SuiteTicket><![CDATA[asdfasfdasdfasdf]]></SuiteTicket>
    </xml>
}

应用提供商在收到ticket推送后需要返回字符串success。

字段说明

参数说明
SuiteId 应用套件的SuiteId
InfoType suite_ticket
TimeStamp 时间戳
SuiteTicket Ticket内容
 为了加强安全性，postdata中的xml将使用应用套件申请时的加解密key来进行加密，具体请见

https://qydev.weixin.qq.com/wiki/index.php?title=%E5%8A%A0%E8%A7%A3%E5%AF%86%E6%96%B9%E6%A1%88%E7%9A%84%E8%AF%A6%E7%BB%86%E8%AF%B4%E6%98%8E

注意需要将corpid替换为suiteid，并忽略AgentID参数

变更授权的通知

当授权方（即授权企业号）在企业号管理端的授权管理中，修改了对套件方的授权托管后，微信服务器会向应用提供商的套件事件接收 URL（创建套件时填写）推送变更授权通知。

https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&amp;timestamp=1403610513&amp;nonce=380320359

POST数据示例

{
    <xml>
        <SuiteId><![CDATA[wxfc918a2d200c9a4c]]></SuiteId>
        <InfoType><![CDATA[change_auth]]></InfoType>
        <TimeStamp>1403610513</TimeStamp>
        <AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
    </xml>
}

应用提供商在收到推送消息后需要返回字符串success

字段说明

参数说明
SuiteId 应用套件的SuiteId
InfoType change_auth
TimeStamp 时间戳
AuthCorpId 授权方企业号的corpid
 为了加强安全性，postdata中的xml将使用应用套件申请时的加解密key来进行加密，具体请见：

https://qydev.weixin.qq.com/wiki/index.php?title=%E5%8A%A0%E8%A7%A3%E5%AF%86%E6%96%B9%E6%A1%88%E7%9A%84%E8%AF%A6%E7%BB%86%E8%AF%B4%E6%98%8E

注意需要将corpid替换为suiteid，并忽略AgentID参数

取消授权的通知

当授权方（即授权企业号）在企业号管理端的授权管理中，取消了对套件方的授权托管后，微信服务器会向应用提供商的套件事件接收 URL（创建套件时填写）推送取消授权通知。

https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&amp;timestamp=1403610513&amp;nonce=380320359

POST数据示例

{
    <xml>
        <SuiteId><![CDATA[wxfc918a2d200c9a4c]]></ SuiteId>
        <InfoType><![CDATA[cancel_auth]]></InfoType>
        <TimeStamp>1403610513</TimeStamp>
        <AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
    </xml>
}

应用提供商在收到推送消息后需要返回字符串success

字段说明

参数说明
SuiteId 应用套件的SuiteId
InfoType cancel_auth
TimeStamp 时间戳
AuthCorpId 授权方企业号的corpid
 为了加强安全性，postdata中的xml将使用应用套件申请时的加解密key来进行加密，具体请见

https://qydev.weixin.qq.com/wiki/index.php?title=%E5%8A%A0%E8%A7%A3%E5%AF%86%E6%96%B9%E6%A1%88%E7%9A%84%E8%AF%A6%E7%BB%86%E8%AF%B4%E6%98%8E

注意需要将corpid替换为suiteid，并忽略AgentID参数

设计资源下载

设计资源下载

为了保证授权体验的一致性，企业号提供了两种授权按钮样式，开发者可通过“鼠标右键另存为”保存按钮图片

授权按钮蓝底：

大

Ld-d.png

中

Ld-z.png

小

Ld-x.png

授权按钮白底：

大

Bd-d.png

中

Bd-z.png

小

Bd-x.png

附录

附录包含了企业号回调企业时加解密的详细方案、库和示例代码的下载，以及企业号api接口返回的错误码。

加解密方案的详细说明

## 目录
## **关于加解密方案的详细说明** ### **术语及说明** 开启回调模式时，有以下术语需要了解：

1.msg_signature是签名，用于验证调用者的合法性。具体算法见以下'消息体签名'章节

2.EncodingAESKey用于消息体的加密，长度固定为43个字符，从a-z, A-Z, 0-9共62个字符中选取，是AESKey的Base64编码。解码后即为32字节长的AESKey

3.AESKey=Base64_Decode(EncodingAESKey + “=”)，是AES算法的密钥，长度为32字节。AES采用CBC模式，数据采用PKCS#7填充；IV初始向量大小为16字节，取AESKey前16字节。具体详见：https://tools.ietf.org/html/rfc2315

4.msg为消息体明文，格式为XML

5.msg_encrypt = Base64_Encode( AES_Encrypt[random(16B) + msg_len(4B) + msg + $CorpID] )，是对明文消息msg加密处理后的Base64编码。其中random为16字节的随机字符串；msg_len为4字节的msg长度，网络字节序；msg为消息体明文；$CorpID为企业号的标识

消息体签名

为了验证调用者的合法性，微信在回调url中增加了消息签名，以参数msg_signature标识，企业需要验证此参数的正确性后再解密。验证步骤：

1.企业计算签名：dev_msg_signature=sha1(sort(token、timestamp、nonce、msg_encrypt))。sort的含义是将参数按照字母字典排序，然后从小到大拼接成一个字符串

2.比较dev_msg_signature和msg_signature是否相等，相等则表示验证通过

在被动响应消息时，企业同样需要用如上方法生成签名并传给微信

加解密方案说明

  • 对明文msg加密的过程如下：
msg_encrypt = Base64_Encode( AES_Encrypt[random(16B) + msg_len(4B) + msg + $CorpID] )

AES加密的buf由16个字节的随机字符串、4个字节的msg长度、明文msg和$CorpID组成。其中msg_len为msg的字节数，网络字节序；$CorpID为企业号的CorpID。经AESKey加密后，再进行Base64编码，即获得密文msg_encrypt。

  • 对应于加密方案，解密方案如下：
1.对密文BASE64解码：aes_msg=Base64_Decode(msg_encrypt)

2.使用AESKey做AES解密：rand_msg=AES_Decrypt(aes_msg)

3.验证解密后$CorpID、msg_len

4.去掉rand_msg头部的16个随机字节，4个字节的msg_len,和尾部的$CorpID即为最终的消息体原文msg

加解密库下载与返回码

加解密库的返回码

返回码说明
0 请求成功
-40001 签名验证错误
-40002 xml解析失败
-40003 sha加密生成签名失败
-40004 AESKey 非法
-40005 corpid 校验错误
-40006 AES 加密失败
-40007 AES 解密失败
-40008 解密后得到的buffer非法
-40009 base64加密失败
-40010 base64解密失败
-40011 生成xml失败

加解密库下载及示例

注意事项：

1.WXBizMsgCrypt.h声明了WXBizMsgCrypt类，提供用户接入企业微信的三个接口。WXBizMsgCrypt.cpp文件提供了三个接口的实现。Sample.cpp文件提供了如何使用这三个接口的示例。

2.WXBizMsgCrypt类封装了VerifyURL, DecryptMsg, EncryptMsg三个接口，分别用于开发者验证回调url，收到用户回复消息的解密以及开发者回复消息的加密过程。使用方法可以参考Sample.cpp文件。

3.加解密协议请参考企业微信官方文档。

4.加解密过程使用了开源的openssl和tinyxml2库，请开发者自行安装之后使用。

   *openssl的版本号是openssl-1.0.1h，https://www.openssl.org/

   *tinyxml2的版本号是tinyxml2-2.1.0，https://github.com/leethomason/tinyxml2

注意事项：

1.WXBizMsgCrypt.py文件封装了WXBizMsgCrypt接口类，提供了用户接入企业微信的三个接口，Sample.py文件提供了如何使用这三个接口的示例，ierror.py提供了错误码。

2.WXBizMsgCrypt封装了VerifyURL, DecryptMsg, EncryptMsg三个接口，分别用于开发者验证回调url、接收消息的解密以及开发者回复消息的加密过程。使用方法可以参考Sample.py文件。

3.本代码用到了pycrypto第三方库，请开发者自行安装此库再使用。

注意事项：

1.WXBizMsgCrypt.php文件提供了WXBizMsgCrypt类的实现，是用户接入企业微信的接口类。Sample.php提供了示例以供开发者参考。errorCode.php, pkcs7Encoder.php, sha1.php, xmlparse.php文件是实现这个类的辅助类，开发者无须关心其具体实现。

2.WXBizMsgCrypt类封装了VerifyURL, DecryptMsg, EncryptMsg三个接口，分别用于开发者验证回调url、接收消息的解密以及开发者回复消息的加密过程。使用方法可以参考Sample.php文件。

注意事项：

1.com\qq\weixin\mp\aes目录下是用户需要用到的接入企业微信的接口，其中WXBizMsgCrypt.java文件提供的WXBizMsgCrypt类封装了用户接入企业微信的三个接口，其它的类文件用户用于实现加解密，用户无须关心。sample.java文件提供了接口的使用示例。

2.WXBizMsgCrypt封装了VerifyURL, DecryptMsg, EncryptMsg三个接口，分别用于开发者验证回调url、接收消息的解密以及开发者回复消息的加密过程。使用方法可以参考Sample.java文件。

3.请开发者使用jdk1.6或以上的版本。针对org.apache.commons.codec.binary.Base64，需要导入jar包commons-codec-1.9（或comm ons-codec-1.8等其他版本），我们有提供，官方下载地址：

https://commons.apache.org/proper/commons-codec/download_codec.cgi

4.异常java.security.InvalidKeyException:illegal Key Size的解决方案：

在官方网站下载JCE无限制权限策略文件（请到官网下载对应的版本， 例如JDK7的下载地址：https://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html )：

下载后解压，可以看到local_policy.jar和US_export_policy.jar以及readme.txt。如果安装了JRE，将两个jar文件放到%JRE_HOME% \lib\security目录下覆盖原来的文件，如果安装了JDK，将两个jar文件放到%JDK_HOME%\jre\lib\security目录下覆盖原来文件。

注意事项：

1.Cryptography.cs文件封装了AES加解密过程，用户无须关心具体实现。WXBizMsgCrypt.cs文件提供了用户接入企业微信的三个接口，Sample.cs文件提供了如何使用这三个接口的示例。

2.WXBizMsgCrypt.cs封装了VerifyURL, DecryptMsg, EncryptMsg三个接口，分别用于开发者验证回调url、接收消息的解密以及开发者回复消息的加密过程。使用方法可以参考Sample.cs文件。

全局返回码说明

企业号每次调用接口时，可能获得正确或错误的返回码，企业可以根据返回码信息调试接口，排查错误。

**全局返回码说明如下：**
<table border="1" cellspacing="0" cellpadding="4" align="center" width="640px">
<tbody><tr>
<th style="width:240px">返回码</th><th>说明</th></tr>
<tr><td> -1</td><td> 系统繁忙</td></tr>
<tr><td> 0</td><td> 请求成功</td></tr>
<tr><td> 40001</td><td> 获取access_token时Secret错误，或者access_token无效</td></tr>
<tr><td> 40002</td><td> 不合法的凭证类型</td></tr>
<tr><td> 40003</td><td> 不合法的UserID</td></tr>
<tr><td> 40004</td><td> 不合法的媒体文件类型</td></tr>
<tr><td> 40005</td><td> 不合法的文件类型</td></tr>
<tr><td> 40006</td><td> 不合法的文件大小</td></tr>
<tr><td> 40007</td><td> 不合法的媒体文件id</td></tr>
<tr><td> 40008</td><td> 不合法的消息类型</td></tr>
<tr><td> 40013</td><td> 不合法的corpid</td></tr>
<tr><td> 40014</td><td> 不合法的access_token</td></tr>
<tr><td> 40015</td><td> 不合法的菜单类型</td></tr>
<tr><td> 40016</td><td> 不合法的按钮个数</td></tr>
<tr><td> 40017</td><td> 不合法的按钮类型</td></tr>
<tr><td> 40018</td><td> 不合法的按钮名字长度</td></tr>
<tr><td> 40019</td><td> 不合法的按钮KEY长度</td></tr>
<tr><td> 40020</td><td> 不合法的按钮URL长度</td></tr>
<tr><td> 40021</td><td> 不合法的菜单版本号</td></tr>
<tr><td> 40022</td><td> 不合法的子菜单级数</td></tr>
<tr><td> 40023</td><td> 不合法的子菜单按钮个数</td></tr>
<tr><td> 40024</td><td> 不合法的子菜单按钮类型</td></tr>
<tr><td> 40025</td><td> 不合法的子菜单按钮名字长度</td></tr>
<tr><td> 40026</td><td> 不合法的子菜单按钮KEY长度</td></tr>
<tr><td> 40027</td><td> 不合法的子菜单按钮URL长度</td></tr>
<tr><td> 40028</td><td> 不合法的自定义菜单使用员工</td></tr>
<tr><td> 40029</td><td> 不合法的oauth_code</td></tr>
<tr><td> 40031</td><td> 不合法的UserID列表</td></tr>
<tr><td> 40032</td><td> 不合法的UserID列表长度</td></tr>
<tr><td> 40033</td><td> 不合法的请求字符，不能包含\uxxxx格式的字符</td></tr>
<tr><td> 40035</td><td> 不合法的参数</td></tr>
<tr><td> 40038</td><td> 不合法的请求格式</td></tr>
<tr><td> 40039</td><td> 不合法的URL长度</td></tr>
<tr><td> 40040</td><td> 不合法的插件token</td></tr>
<tr><td> 40041</td><td> 不合法的插件id</td></tr>
<tr><td> 40042</td><td> 不合法的插件会话</td></tr>
<tr><td> 40048</td><td> url中包含不合法domain</td></tr>
<tr><td> 40054</td><td> 不合法的子菜单url域名</td></tr>
<tr><td> 40055</td><td> 不合法的按钮url域名</td></tr>
<tr><td> 40056</td><td> 不合法的agentid</td></tr>
<tr><td> 40057</td><td> 不合法的callbackurl</td></tr>
<tr><td> 40058</td><td> 不合法的红包参数</td></tr>
<tr><td> 40059</td><td> 不合法的上报地理位置标志位</td></tr>
<tr><td> 40060</td><td> 设置上报地理位置标志位时没有设置callbackurl</td></tr>
<tr><td> 40061</td><td> 设置应用头像失败</td></tr>
<tr><td> 40062</td><td> 不合法的应用模式</td></tr>
<tr><td> 40063</td><td> 红包参数为空</td></tr>
<tr><td> 40064</td><td> 管理组名字已存在</td></tr>
<tr><td> 40065</td><td> 不合法的管理组名字长度</td></tr>
<tr><td> 40066</td><td> 不合法的部门列表</td></tr>
<tr><td> 40067</td><td> 标题长度不合法</td></tr>
<tr><td> 40068</td><td> 不合法的标签ID</td></tr>
<tr><td> 40069</td><td> 不合法的标签ID列表</td></tr>
<tr><td> 40070</td><td> 列表中所有标签（用户）ID都不合法</td></tr>
<tr><td> 40071</td><td> 不合法的标签名字，标签名字已经存在</td></tr>
<tr><td> 40072</td><td> 不合法的标签名字长度</td></tr>
<tr><td> 40073</td><td> 不合法的openid</td></tr>
<tr><td> 40074</td><td> news消息不支持指定为高保密消息</td></tr>
<tr><td> 40077</td><td> 不合法的预授权码</td></tr>
<tr><td> 40078</td><td> 不合法的临时授权码</td></tr>
<tr><td> 40079</td><td> 不合法的授权信息</td></tr>
<tr><td> 40080</td><td> 不合法的suitesecret</td></tr>
<tr><td> 40082</td><td> 不合法的suitetoken</td></tr>
<tr><td> 40083</td><td> 不合法的suiteid</td></tr>
<tr><td> 40084</td><td> 不合法的永久授权码</td></tr>
<tr><td> 40085</td><td> 不合法的suiteticket</td></tr>
<tr><td> 40086</td><td> 不合法的第三方应用appid</td></tr>
<tr><td> 41001</td><td> 缺少access_token参数</td></tr>
<tr><td> 41002</td><td> 缺少corpid参数</td></tr>
<tr><td> 41003</td><td> 缺少refresh_token参数</td></tr>
<tr><td> 41004</td><td> 缺少secret参数</td></tr>
<tr><td> 41005</td><td> 缺少多媒体文件数据</td></tr>
<tr><td> 41006</td><td> 缺少media_id参数</td></tr>
<tr><td> 41007</td><td> 缺少子菜单数据</td></tr>
<tr><td> 41008</td><td> 缺少oauth code</td></tr>
<tr><td> 41009</td><td> 缺少UserID</td></tr>
<tr><td> 41010</td><td> 缺少url</td></tr>
<tr><td> 41011</td><td> 缺少agentid</td></tr>
<tr><td> 41012</td><td> 缺少应用头像mediaid</td></tr>
<tr><td> 41013</td><td> 缺少应用名字</td></tr>
<tr><td> 41014</td><td> 缺少应用描述</td></tr>
<tr><td> 41015</td><td> 缺少Content</td></tr>
<tr><td> 41016</td><td> 缺少标题</td></tr>
<tr><td> 41017</td><td> 缺少标签ID</td></tr>
<tr><td> 41018</td><td> 缺少标签名字</td></tr>
<tr><td> 41021</td><td> 缺少suiteid</td></tr>
<tr><td> 41022</td><td> 缺少suitetoken</td></tr>
<tr><td> 41023</td><td> 缺少suiteticket</td></tr>
<tr><td> 41024</td><td> 缺少suitesecret</td></tr>
<tr><td> 41025</td><td> 缺少永久授权码</td></tr>
<tr><td> 42001</td><td> access_token超时</td></tr>
<tr><td> 42002</td><td> refresh_token超时</td></tr>
<tr><td> 42003</td><td> oauth_code超时</td></tr>
<tr><td> 42004</td><td> 插件token超时</td></tr>
<tr><td> 42007</td><td> 预授权码失效</td></tr>
<tr><td> 42008</td><td> 临时授权码失效</td></tr>
<tr><td> 42009</td><td> suitetoken失效</td></tr>
<tr><td> 43001</td><td> 需要GET请求</td></tr>
<tr><td> 43002</td><td> 需要POST请求</td></tr>
<tr><td> 43003</td><td> 需要HTTPS</td></tr>
<tr><td> 43004</td><td> 需要接收者关注</td></tr>
<tr><td> 43005</td><td> 需要好友关系</td></tr>
<tr><td> 43006</td><td> 需要订阅</td></tr>
<tr><td> 43007</td><td> 需要授权</td></tr>
<tr><td> 43008</td><td> 需要支付授权</td></tr>
<tr><td> 43009</td><td> 需要员工已关注</td></tr>
<tr><td> 43010</td><td> 需要处于回调模式</td></tr>
<tr><td> 43011</td><td> 需要企业授权</td></tr>
<tr><td> 44001</td><td> 多媒体文件为空</td></tr>
<tr><td> 44002</td><td> POST的数据包为空</td></tr>
<tr><td> 44003</td><td> 图文消息内容为空</td></tr>
<tr><td> 44004</td><td> 文本消息内容为空</td></tr>
<tr><td> 45001</td><td> 多媒体文件大小超过限制</td></tr>
<tr><td> 45002</td><td> 消息内容超过限制</td></tr>
<tr><td> 45003</td><td> 标题字段超过限制</td></tr>
<tr><td> 45004</td><td> 描述字段超过限制</td></tr>
<tr><td> 45005</td><td> 链接字段超过限制</td></tr>
<tr><td> 45006</td><td> 图片链接字段超过限制</td></tr>
<tr><td> 45007</td><td> 语音播放时间超过限制</td></tr>
<tr><td> 45008</td><td> 图文消息超过限制</td></tr>
<tr><td> 45009</td><td> 接口调用超过限制</td></tr>
<tr><td> 45010</td><td> 创建菜单个数超过限制</td></tr>
<tr><td> 45015</td><td> 回复时间超过限制</td></tr>
<tr><td> 45016</td><td> 系统分组，不允许修改</td></tr>
<tr><td> 45017</td><td> 分组名字过长</td></tr>
<tr><td> 45018</td><td> 分组数量超过上限</td></tr>
<tr><td> 45024</td><td> 账号数量超过上限</td></tr>
<tr><td> 46001</td><td> 不存在媒体数据</td></tr>
<tr><td> 46002</td><td> 不存在的菜单版本</td></tr>
<tr><td> 46003</td><td> 不存在的菜单数据</td></tr>
<tr><td> 46004</td><td> 不存在的员工</td></tr>
<tr><td> 47001</td><td> 解析JSON/XML内容错误</td></tr>
<tr><td> 48002</td><td> Api禁用</td></tr>
<tr><td> 48003</td><td> suitetoken无效</td></tr>
<tr><td> 48004</td><td> 授权关系无效</td></tr>
<tr><td> 50001</td><td> redirect_uri未授权</td></tr>
<tr><td> 50002</td><td> 员工不在权限范围</td></tr>
<tr><td> 50003</td><td> 应用已停用</td></tr>
<tr><td> 50004</td><td> 员工状态不正确（未关注状态）</td></tr>
<tr><td> 50005</td><td> 企业已禁用</td></tr>
<tr><td> 60001</td><td> 部门长度不符合限制</td></tr>
<tr><td> 60002</td><td> 部门层级深度超过限制</td></tr>
<tr><td> 60003</td><td> 部门不存在</td></tr>
<tr><td> 60004</td><td> 父亲部门不存在</td></tr>
<tr><td> 60005</td><td> 不允许删除有成员的部门</td></tr>
<tr><td> 60006</td><td> 不允许删除有子部门的部门</td></tr>
<tr><td> 60007</td><td> 不允许删除根部门</td></tr>
<tr><td> 60008</td><td> 部门名称已存在</td></tr>
<tr><td> 60009</td><td> 部门名称含有非法字符</td></tr>
<tr><td> 60010</td><td> 部门存在循环关系</td></tr>
<tr><td> 60011</td><td> 管理员权限不足，（user/department/agent）无权限</td></tr>
<tr><td> 60012</td><td> 不允许删除默认应用</td></tr>
<tr><td> 60013</td><td> 不允许关闭应用</td></tr>
<tr><td> 60014</td><td> 不允许开启应用</td></tr>
<tr><td> 60015</td><td> 不允许修改默认应用可见范围</td></tr>
<tr><td> 60016</td><td> 不允许删除存在成员的标签</td></tr>
<tr><td> 60017</td><td> 不允许设置企业</td></tr>
<tr><td> 60019</td><td> 不允许设置应用地理位置上报开关</td></tr>
<tr><td> 60020</td><td> 访问ip不在白名单之中</td></tr>
<tr><td> 60102</td><td> UserID已存在</td></tr>
<tr><td> 60103</td><td> 手机号码不合法</td></tr>
<tr><td> 60104</td><td> 手机号码已存在</td></tr>
<tr><td> 60105</td><td> 邮箱不合法</td></tr>
<tr><td> 60106</td><td> 邮箱已存在</td></tr>
<tr><td> 60107</td><td> 微信号不合法</td></tr>
<tr><td> 60108</td><td> 微信号已存在</td></tr>
<tr><td> 60109</td><td> QQ号已存在</td></tr>
<tr><td> 60110</td><td> 部门个数超出限制</td></tr>
<tr><td> 60111</td><td> UserID不存在</td></tr>
<tr><td> 60112</td><td> 成员姓名不合法</td></tr>
<tr><td> 60113</td><td> 身份认证信息（微信号/手机/邮箱）不能同时为空</td></tr>
<tr><td> 60114</td><td> 性别不合法</td></tr>
<tr><td> 60023</td><td> 应用已授权予第三方，不允许通过分级管理员修改菜单</td></tr></tbody></table>
<!--
NewPP limit report
CPU time usage: 0.020 seconds
Real time usage: 0.019 seconds
Preprocessor visited node count: 1/1000000
Preprocessor generated node count: 4/1000000
Post‐expand include size: 0/2097152 bytes
Template argument size: 0/2097152 bytes
Highest expansion depth: 1/40
Expensive parser function count: 0/100
-->
<!-- Saved in parser cache with key db_wiki:pcache:idhash:25-0!*!*!*!*!*!* and timestamp 20150116090425 and revision id 683
 -->