企业微信开发指南

假设你对企业微信有了基本的了解——也就是说，你知道什么是企业微信，为什么要做企业微信开发。

企业微信的发展主要包括以下几个方面：

通讯录管理应用管理消息推送材料管理身份验证JS-SDK

微信官方在这些方面提供了非常详细的文档(见参考链接)，本文不再赘述。这里只选择几个常见的开发场景来分享我自己的经验。

通讯录

通讯录由部门 员工组成，两者关系多对多，部门只有部门ID（department_id），员工有唯一的账户（userid）。

userid：即通讯录中的账号字段，新员工档案由管理员填写，功能与官方账号相似openid，同一企业号下唯一；department_id：部门ID(点击通讯录/组织架构树/各部门/右上角按钮查看)，新建时微信自动生成，同一企业号下唯一；标签:本质上是部门和员工的逻辑分组。

应用

按提供方来分有三种：

基本应用程序：由微信提供；第三方应用程序：由开放系统下的第三方服务提供商提供；自建应用程序：我们自己的新应用程序，我们通常需要自建应用程序来开发。

按作用分为两种：

主页应用程序：用户点击应用程序后直接打开链接；新闻应用程序：可以设置多个菜单，每个菜单可以配置不同的响应方式。

以下是一个应用程序详情界面：

应用详情

从上图可以看出，一个应用程序主要包含以下信息：

AgentId：应用ID，新应用后由微信生成；Secret：应用的Secret，结合CorpID用来获取access_token；可见范围：谁能看到这个应用程序（可以根据人、部门或标签设置）；管理员：可以管理应用程序的人；可信域名：应用程序主页链接和菜单链接必须是可信域名下的地址，由域名 端口（80或443）组成http:// ** .example.com或http://test.example.com:3000，需要注意的是，域名必须通过记录；工作台应用程序主页：配置用户点击应用程序后跳转的链接地址。配置后，应用程序为主页应用程序；自定义菜单：设置后，表示应用程序为新闻工作台应用程序主页链接将无效，设置方法与公共账户相似。

访问令牌

访问令牌（access_token）这是我们开发的第一步。在调用微信接口之前，我们经常需要获得令牌，然后才能为所欲为 ：- )。

令牌只能通过企业ID（CorpID） Secret来获取，CorpID检查方法如下：

每个企业号CorpID但是Secret但是有几种不同Secret获得的令牌作用范围不同。

Secret分类如下：

应用Secret：点击应用细节查看通讯录管理Secret：管理工具/通讯录同步讯录同步管理组Secret：查看方法是我的企业/权限管理/管理组(找不到很正常，因为这是老用户的待遇，已经退出历史舞台，奸笑ing）。应用Secret通讯录管理Secret曾经的管理组Secret

获取令牌的接口是：

GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=CORPID&corpsecret=SECRECT

返回格式如下：

{ "errcode": 0, "errmsg": "", "access_token": "accesstoken000001", "expires_in": 7200}

需要注意的是access_token有时效性，超过7200（expires_in值)秒后过期，由于接口访问频率有限，需要定期刷新access_token。

详情请参考：获取access_token - 企业微信。

场景一：网页授权登录参考文档：网页授权登录 - 企业微信

这是我们使用频率最高的场景。简单来说，用户进入应用时如何获得他？userid(或更详细的信息)？

授权登录使用OAuth2.0先来看看微信官方提供的接入流程图:

总结为三个步骤：

当用户访问微信服务器时，您需要告诉微信服务器跳转地址微信服务器进行验证，验证后返回您提供的地址，并带来与用户信息相关的地址code你根据这个code再次调用另一个接口获取用户数据

第一步和第二步都是为了得到code，第三步是获取用户信息。

假如我有一个主页应用程序，基本信息如下：

企业ID：wx10101可信域名：test.example.com:3000回调地址：https://test.example.com:3000/api/myredirect

所以生成的网页链接是这样的(链接可以设置为主页地址、菜单链接和推送消息的跳转链接):

https://open.weixin.qq.com/connect/oauth2/authorize?appid=wx10101&redirect_uri=https://test.example.com:3000/api/myredirect&response_type=code&scope=snsapi_base#wechat_redirect

这里有两点需要注意:

redirect_uri值必须通过urlencode处理(可直接调用)JS的全局函数encodeURIComponent）redirect_uri的host如果您即域名 端口)必须与可信域名配置一致。如果您将一些信息从用户点击传输到回调地址，可以设置state参数(只有这种传递方式)

获取用户信息的接口是(注意)code只能用一次):

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

场景二:扫码授权登录参考文件:扫码授权登录 - 企业微信

这里只讨论一下Web网页扫码登录场景，移动扫码登录请参考官方文件。

在开发扫码登录之前，您需要先打开应用程序的网页接入功能，点击应用程序细节/企业微信授权登录/Web网页，可信域名的值 ** 过来设置。

扫码登录类似于场景，也是OAuth2.0先拿协议code交互流程图如下：

假如我有以下基本信息：

企业ID：wx10101应用ID：1000000可信域名：http://test.example.com:3000回调地址：https://test.example.com:3000/api/myredirect

所以生成的扫码链接是这样的:

https://open.work.weixin.qq.com/wwopen/sso/qrConnect?appid=wx10101&agentid=1000000&redirect_uri=https://test.example.com:3000/api/myredirect

用户打开链接后，会出现二维码。用户使用企业微信扫描代码后，会跳转到回调地址并带授权code，通过code获取用户信息的接口为：

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

场景3：材料管理参考文件：材料管理 - 企业微信

素材管理比较简单，直接调用微信接口即可，不过需要注意的是，目前企业微信只开放了临时素材的管理接口（今天是2018-05-04），所有通过接口上传的media_id三天内有效。

所以如果我需要永久性的话media_id怎么做？这里分享一个黑科技。

比如要上传图片素材：

首先打开管理工具/素材库/图片界面；然后打开浏览器控制台（F12或者com ** nd option i或者其他快捷键）；再打开Network页面签名准备查看网络请求(为了查看方便，可以先清空)。此时，点击添加图片上传。如果上传成功，Network请求参数将出现在页面签名中，包含您想要的参数media_id啦。

场景4：信息推送参考文件：发送应用信息 - 企业微信

本质上只是调用接口。

需要注意的是，消息是以应用程序为单位显示的(发送消息时指定agentid），因此，您调用接口使用的接口access_token必须通过该应用Secret获得的。

如果你想排版消息(使用)html用户点击后，您希望跳转到网页地址，我推荐您使用文本卡消息。

我们以前也遇到过一个场景，希望用户在点击信息后跳转到其他应用程序，但不幸的是，微信不支持跨应用程序跳转。

场景五：JS-SDK参考文档：JS-SDK - 企业微信

要用JS-SDK，必须进行客户端SDK初始化；

要初始化，必须有签名；

要有签名，必须有签名jsapi_ticket。

让我们先谈谈jsapi_ticket。jsapi_ticket其实跟access_token同样，它也会过期，并且有频率限制，所以我们也需要jsapi_ticket定期刷新，获取jsapi_ticket接口如下：

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

接下来是签名，分享一个node签名算法供参考：

const crypto = require('crypto');const qs = require('querystring');/** * 签名生成算法 * @param {*} query */function sign(query) { / 1.排序 const obj = qs.parse(query); const message = Object.keys(obj).sort(). ** p(key => `${key}=${obj[key]}`).join('&'); // 2.加密 const signature = crypto.createHash('sha1').update(message,'utf8').digest('hex'); return signature;}// 测试const query = 'noncestr=Wm3WZYTPz0wzccnW&jsapi_ticket=sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg&timestamp=1414587457&url=http://mp.weixin.qq.com?params=value';console.log(sign(m));// => 0f9de62fce790f9a083d5c99e95740ceb90c27ed

如果您不确定您的算法是否正确，可以到微信提供的在线签名工具进行验证。

有了签名，我们就可以了SDK初始化需要在初始化前引入js文件：

http://res.wx.qq.com/open/js/jweixin-1.2.0.js（支持https）

然后开始实施初始化:

wx.config({ beta: true, // 必须这样写，否则，wx.invoke调用形式的jsapi 会有问题debug: true, // 打开调试模式，调用所有api返回值将在客户端alert如果要查看输入参数，可以在pc端打开，参数信息通过log打出，仅在pc端时打印appId: '', corpID timestamp: '', // 必填，生成签名的时间戳 nonceStr: '', // 必填，生成签名的随机串 signature: '', // 必填，签名，见附录1 jsApiList: [] // 必填，需要使用的JS接口列表，所有JS接口列表见附录2});// 成功回调readywx.ready(function(){ // config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异步操作，所以如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中。});// 失败回调errorwx.error(function(res){ // config信息验证失败会执行error函数，如签名过期导致验证失败，具体错误信息可以打开config的debug模式查看，也可以在返回的res参数中查看，对于SPA可以在这里更新签名。});

这里需要注意的是所有参数都是大小写敏感的，比如后端签名时参数是noncestr，但是前端初始化时是nonceStr。

初始化成功后，就可以尽情地浪了。使用企业微信打开以下链接即可体验官方提供的Demo页面：

http://work.weixin.qq.com/api/jsapidemo (二维码自动识别)

最后说两句严格按照文档中要求的去做会少栽很多坑，不要看漏任何一个细节，例如大小写；如果你已经按照文档要求去做了，还是未达到理想效果，那你可以安装一个开发者工具，尝试下从控制台输出信息去进行调试（微信的开发者工具是可以模拟整个微信环境的）；如果还是解决不了你的问题，那你就直接找客服吧（企业微信的客服反馈还是很及时的，在企业微信客户端的客服对话框中，输入“人工”即可）。企业微信客服入口参考链接

开发文档 - 企业微信