微信企业号第三方应用开发[一]——创建套件
注:文中绿色部分为摘自微信官方文档
第三方应用提供给企业的是一个应用,但是应用必须在套件下创建,所以第一步是要创建套件。
注册成为应用提供商,必须输入以下信息:
信息项 | 要求及说明 |
---|---|
企业Logo | 应用提供商的企业Logo,小于2M,640*640,背景为白色 |
企业简称 | 使用对外宣传的企业简称,能代表企业的名字,2-16个字 |
企业简介 | 描述企业所提供的服务,4-120个字 |
企业官网 | 应用服务商的企业官网 |
注册条件:a)拥有一个已经过认证的企业号 b)用系统管理员身份进行申请
符合以上条件后,登录微信第三方应用官网,选择“服务商登录”
创建应用套件
开发者完成注册之后,即可创建应用套件。应用套件是第三方应用授权的主体,接口的开发都与应用套件息息相关,请开发者仔细阅读下方内容。
基本信息:
信息项 | 要求及说明 |
---|---|
应用套件Logo | 应用套件的Logo,小于2M,640*640,在授权页会被用于展示。 |
应用套件名称 | 应用套件的名称,2-16个字 |
介绍网站 | 介绍该应用套件网站或者页面 |
应用套件介绍 | 描述该应用套件所提供的服务,4-120个字 |
授权方式 | 使用方式目前有两种:线上自助注册授权使用和服务商辅助授权使用。 |
服务行业 | 该应用套件所服务的行业对象,一个套件只能属于一个服务行业。 |
套件标签 | 套件提供的服务类型,如OA办公、CRM、HR、ERP等。一个套件只能拥有一个标签。 |
注意:
1)你应谨慎选择所填写的行业和标签,行业是指可使用该套件企业所属的行业。当应用套件达到一定的活跃度后(授权企业数和日活跃用户数),会自动在企业号第三方官网进行推荐,套件所在的分类将基于所设置的行业和标签。
2)授权方式的作用在于区分应用套件是否可以直接从企业号第三方官网发起授权,线上自助注册授权使用是指该应用套件可以直接从企业号第三方官网发起授权,而不跳转服务商网站,该类型的应用套件还可以支持移动端发起应用套件授权;服务商辅助授权使用是指该应用套件必须跳转服务商网站,从服务商网站发起应用套件的授权,该类型的应用套件不支持移动端发起应用套件授权。
3)你可以创建或者选择其他开发者已创建的标签。你应该谨慎选择套件标签,用户往往会在企业号中通过标签查找相关联的套件。
开发信息:
套件参数内容 | 说明 |
---|---|
发起授权域名 | 在该域名下发起的授权请求才可被通过,企业点击授权链接时,企业号会检查该域名是否已登记。 |
授权完成回调域名 | 在第三方应用授权流程中,授权成功后会回调该域名,返回临时code。你需用此code换取永久授权码,请尽量将此域名与发起授权域名保持一致。 |
系统事件接收URL | 系统将会把此套件的授权变更事件以及ticket参数推送给此URL,ticket说明详见API接口说明。(填写URL时需要正确响应微信验证URL的请求,具体说明请阅读“回调模式”) |
Token | 可任意填写,用于生成签名,校验回调请求的合法性。后续所有托管的企业产生的回调消息都使用该值来解密。 |
EncodingAESKey | 回调消息加解密参数,是AES密钥的Base64编码,用于解密回调消息内容对应的密文。后续所有托管的企业产生的回调消息都使用该值来解密。 |
应用套件ID | 应用套件的编号,相关的接口调用需要使用,由系统生成,不可更改。 |
应用套件secret | 应用套件的密钥,相关的接口调用需要使用。 |
白名单IP列表 | 应用套件调用企业号第三方应用API时的合法IP列表,只有白名单内的IP才能正常调用企业号API,后续IP若有修改,需要及时进行列表更新。 |
创建完成之后,系统会告知开发者该应用套件的Suiteid和Suitesecret。(详见第三方应用接口说明)
登陆后界面如下,选择添加应用套件
进入创建套件页面,填写基本资料
点击下一步,填写开发资料
验证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明文(不能加引号,不能带bom头,不能带换行符),则接入验证生效,回调模式才能开启。
摘自http://qydev.weixin.qq.com/wiki/index.php?title=%E5%9B%9E%E8%B0%83%E6%A8%A1%E5%BC%8F
"系统事件接收URL"响应的代码如下
/** * 测试微信企业号第三方应用回调协议 * @author:leap * @MethodName: testWXSaaSCallback * @Description: * @param req * @param res * @date:2016-8-9 */ @RequestMapping(value="testWXSaaSCallback") @ResponseBody public void testWXSaaSCallback( HttpServletRequest req, ServletResponse res){ //常量值 String CORP_ID = "wx9671de0651dbdxxx"; //CorpId, 企业号的普通管理组中可查看 String SUITE_ID = "tja2312bedd5086xxx"; //套件ID,在套件信息中查看 String SUITE_SECRET = "LGVT0BrN2DZ7VMTuIPOsudaWuXOE0iM67yHpIs1ofESS4l-jSC8LN9nOnmilhXXX"; String SUITE_TOKEN = "ssI2AnbgOo40eb0kOxxx"; String SUITE_ENCODING_AES_KEY = "Pmqgjzwt4yAEK9N6YZ34RKpy6onJD56r8mhCUFG9xxx"; //获取参数 String msgSignature = req.getParameter("msg_signature"); String timestamp = req.getParameter("timestamp"); String nonce = req.getParameter("nonce"); String echostr = req.getParameter("echostr"); //创建套件时验证回调url时传入 String result = ""; try { if(!Utils.isBlank(echostr)){ //=======验证回调url有效性======= WXBizMsgCrypt wxBizMsgCrypt = new WXBizMsgCrypt(SUITE_TOKEN, SUITE_ENCODING_AES_KEY, CORP_ID);//注意是CORP_ID result = wxBizMsgCrypt.VerifyURL(msgSignature, timestamp, nonce, echostr); System.out.println(result); res.getWriter().write(result); //对echostr参数解密并原样返回echostr明文(不能加引号,不能带bom头,不能带换行符) }else{ //其他操作 res.getWriter().write("false"); } } catch (Exception e) { e.printStackTrace(); } }
其中类WXBizMsgCrypt由官方提供
注意事项:
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(或commons-codec-1.8等其他版本),我们有提供,官方下载地址:
http://commons.apache.org/proper/commons-codec/download_codec.cgi
4.异常java.security.InvalidKeyException:illegal Key Size的解决方案:
在官方网站下载JCE无限制权限策略文件(请到官网下载对应的版本, 例如JDK7的下载地址:http://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目录下覆盖原来文件。
红字部分是必要操作,不可忽略