企业微信第三方开发课程 14-18

一、简介

这里主要分为四部分，验证 url 有效性、完成用户的测试安装、获取生成预授权码、生成授权安装链接。这几部就可以完成第三方有用的回调和安装，这也是后续功能开发的基础。

二、Get 请求验证 URL 有效性

1.为什么要搭建回调服务

在集成企业微信与内部系统时，搭建一个回调服务可以获取到用户通过企业微信发送给应用的消息：

自定义丰富的服务行为。比如，用户向应用发消息时，识别消息关键词，回复不同的消息内容；
用户点击应用菜单时，转化为指令，执行自动化任务。
可以及时获取到状态变化。比如，通讯录发生变化时，不需要定时去拉取通讯录对比，而是实时地获取到变化的通讯录结点，进行同步。

2.验证 url 的有效性

回调服务的 url 是由第三方应用的开发商所提供的，在我们将配置好的 url 填入到回调配置的内容里，点击【确定】按钮时会调用一个 Get 请求来验证我们提供的这个 url 的有效性，下面向大家展示如何使验证通过。

验证流程：

我们将 url 填入后点击【确定】，企业微信会发送一条 Get 请求携带签名以及密文到 url 服务上。(每次点击确定都会发送这个 get 请求)
我们的 url 收到请求后需要接收四个参数：
- msg_signature String 企业微信加密签名
- timestamp Integer 时间戳。与 nonce 结合使用，用于防止请求重放攻击。
- nonce String 随机数。与 timestamp 结合使用，用于防止请求重放攻击。
- echostr String 加密的字符串。需要解密得到消息内容明文，解密后有 random、msg_len、msg、receiveid 四个字段，其中 msg 即为消息内容明文，receiveid 应该与企业 ID 相同，会在验证时进行比对。
将接收的参数传递到企微提供的解密的方法 wxcpt.VerifyURL 里可以进行解密，返回解密后的明文字符串，也就是 msg。如果返回的明文是正确的，则验证通过
整个过程需要在 1s 内完成，而且返回的字符串不可以添加引号、空格、换行符等
验证通过后我们就可以通过一个 post 请求获取到 Ticket

三、Post 请求接收业务数据，完成测试安装

当有企业安装了我们的应用，可以通过这个请求获取到到企业的一些信息。

1.接收请求传递的参数

a. 请求在发送时会携带三个参数在 url 中,以及一个 xml 字符串在 body 中：

msg_signature String 企业微信加密签名，msg_signature 结合了企业填写的 token、请求中的 timestamp、nonce 参数、加密的消息体
timestamp Integer 时间戳。与 nonce 结合使用，用于防止请求重放攻击。
nonce String 随机数。与 timestamp 结合使用，用于防止请求重放攻击。
xml 字符串包括
- SuiteId 第三方应用的 SuiteId
- AuthCode 临时授权码,最长为 512 字节。用于获取企业永久授权码。10 分钟内有效，特别重要
- InfoType create_auth
- TimeStamp 时间戳
- State 构造授权链接指定的 state 参数

b. 在第三方回调事件中使用加解密算法，receiveid 的内容为 suiteid，所以我们需要使用 suiteid 进行解密，这个与 Get 请求 url 验证的方法是不同的，需要区分。

c. 通过 wxcpt.DecryptMsg()方法传递解密传递过来的 msg_signature、timestamp、nonce、body 四个参数，解密后我们就可以获取使用 body 里面的 SuiteId 、AuthCode、InfoType、TimeStamp 、State 这几个参数了。

d. 最后需要在 1s 内返回一个字符串“success”否者会被企业微信当中错误的消息，其他 POST 请求的解密方法基本都相同。

四、获取生成预授权码

当用户在第三方服务商的网站安装应用时，需要先获取到临时授权码(预授权码)才可以进行后面的安装操作。

获取预授权码流程：

获取 suite_ticket
通过 suite_ticket 获取第三方应用凭证
通过第三方应用凭证获取预授权码

1.获取接收 suite_ticket

获取 suite_ticket 流程：

企业微信会通过一个 POST 请求每十分钟向我们的应用推送一个 suite_ticket，仅三十分钟有效
获取到 ticket 后我们将这个 ticket 保存下来去通过它获取第三方应用凭证
如果我们需要立即获取到 ticket 的话，可以在服务商官网，在第三方应用详情-回调配置，手动刷新 ticket 推送。

2.获取第三方应用凭证

获取第三方应用凭证流程：

通过一个 POST 请求来获取凭证

请求类型: POST请求url:https://qyapi.weixin.qq.com/cgi-bin/service/get_suite_tokenbody:
{"suite_id":"wwddddccc7775555aaa" ,"suite_secret": "ldAE_H9anCRN21GKXVfdAAAAAAAAAAAAAAAAAA","suite_ticket": "Cfp0_givEagXcYJIztF6sfbdmIZCmpaR8ZBsvJEFFNBrWmnD5-CGYJ3_NhYexMyw"
}参数介绍:
suite_id	必填	以ww或wx开头的应用id（对应于旧的以tj开头的套件id）
suite_secret	必填	应用的secret
suite_ticket	必填	企业微信后台推送的ticket

在服务商后台，应用管理，应用详情里可以查看 suite_id 与 suite_secret，如下图

信息填写正确后就可以得到返回值，suite_access_token 包含在返回结果内，接下来通过 suite_access_token 来获取预授权码

返回结果：

{"errcode":0 ,"errmsg":"ok" ,"suite_access_token":"61W3mEpU66027wgNZ_MhGHNQDHnFATkDa9-2llMBjUwxRSNPbVsMmyD-yq8wZETSoE5NQgecigDrSHkPtIYA","expires_in":7200
}

3.获取预授权码

获取获取预授权码流程：

获取预授权码需要向企微发送一个 GET 请求

请求类型: GET请求url:https://qyapi.weixin.qq.com/cgi-bin/service/get_pre_auth_code?suite_access_token=SUITE_ACCESS_TOKEN请求参数：suite_access_token	必填	刚刚获取到的第三方应用access_token,最长为512字节

当请求成功后可以得到返回值，预授权码在返回值内

返回结果：

{"errcode":0 ,"errmsg":"ok" ,"pre_auth_code":"Cx_Dk6qiBE0Dmx4EmlT3oRfArPvwSQ-oa3NL_fwHM7VI08r52wazoZX2Rhpz1dEw","expires_in":1200
}参数介绍：
pre_auth_code	预授权码,最长为512字节
expires_in	有效期（秒）

五、生成应用授权安装链接并进行安装

获取预授权码后我们就可以生成我们自己的授权链接，用户进入我们的网站点击后确认后返回临时授权码、过期时间以及 state 参数。第三方服务商据此获得临时授权码，临时授权码 10 分钟后会失效，我们可以使用临时授权码换取永久授权码及授权信息。进而调用企业微信相关 API 为授权企业提供服务。

1.设置安装链接

链接地址：
https://open.work.weixin.qq.com/3rdapp/install?suite_id=SUITE_ID&pre_auth_code=PRE_AUTH_CODE&redirect_uri=REDIRECT_URI&state=STATE链接参数：
suite_id 企业的suiteID
pre_auth_code 上一步获取的预授权码
redirect_uri 授权完成后的回调网址，redirect_uri需要经过一次urlencode作为参数
state 可填a-zA-Z0-9的参数值（不超过128个字节），用于第三方自行校验session，防止跨域攻击。

2.设置授权配置

如果我们直接点击上面的测试安装链接会提示该应用已下线，这是以为我们的应用还在测试阶段，我们需要先调用一个设置授权配置的 POST 请求来讲应用改为测试应用，请求详情如下

请求方式：POST（HTTPS）请求地址： https://qyapi.weixin.qq.com/cgi-bin/service/set_session_info?suite_access_token=SUITE_ACCESS_TOKENbody:
{"pre_auth_code":"xxxxx","session_info":{"appid":[1,2,3],"auth_type":1}
}参数说明：
suite_access_token	必填	第三方应用access_token
pre_auth_code	必填	预授权码
session_info	必填	本次授权过程中需要用到的会话信息
appid	非必填	允许进行授权的应用id，如1、2、3， 不填或者填空数组都表示允许授权套件内所有应用（仅旧的多应用套件可传此参数，新开发者可忽略）
auth_type	非必填	授权类型：0 正式授权， 1 测试授权。 默认值为0。(在发布后记得改为正式授权)返回结果：
{"errcode": 0,"errmsg": "ok"
}

3.获取永久授权码

用户点击我们的安装链接并确认后会跳回，在跳回的 url 里会携带 auth_code(临时授权码)，通过临时授权码我们可以发送一个 POST 请求来获取永久授权码。

永久授权码非常重要，临时授权码一次有效。我们获取永久授权码时会一并讲安装我们应用的公司的详细信息返回给我们，其中的 corpid(授权方企业微信 id)以及 permanent_code( 企业微信永久授权码,最长为 512 字节)是执行后面功能性接口的基础，非常重要，需要妥善保管。

请求详情如下：

请求方式：POST（HTTPS）请求地址： https://qyapi.weixin.qq.com/cgi-bin/service/get_permanent_code?suite_access_token=SUITE_ACCESS_TOKENbody：
{"auth_code": "auth_code_value"
}参数说明：auth_code	必填	临时授权码，会在授权成功时附加在redirect_uri中跳转回第三方服务商网站返回结果：
{"errcode":0 ,"errmsg":"ok" ,"access_token": "xxxxxx","expires_in": 7200,"permanent_code": "xxxx","dealer_corp_info":{"corpid": "xxxx","corp_name": "name"},"auth_corp_info":{"corpid": "xxxx","corp_name": "name","corp_type": "verified","corp_square_logo_url": "yyyyy","corp_user_max": 50,"corp_agent_max": 30,"corp_full_name":"full_name","verified_end_time":1431775834,"subject_type": 1,"corp_wxqrcode": "zzzzz","corp_scale": "1-50人","corp_industry": "IT服务","corp_sub_industry": "计算机软件/硬件/信息服务"},"auth_info":{"agent" :[{"agentid":1,"name":"NAME","round_logo_url":"xxxxxx","square_logo_url":"yyyyyy","appid":1,"auth_mode":1,"is_customized_app":false,"privilege":{"level":1,"allow_party":[1,2,3],"allow_user":["zhansan","lisi"],"allow_tag":[1,2,3],"extra_party":[4,5,6],"extra_user":["wangwu"],"extra_tag":[4,5,6]},"shared_from":{"corpid":"wwyyyyy"}},{"agentid":2,"name":"NAME2","round_logo_url":"xxxxxx","square_logo_url":"yyyyyy","appid":5,"shared_from":{"corpid":"wwyyyyy"}}]},"auth_user_info":{"userid":"aa","open_userid":"xxxxxx","name":"xxx","avatar":"http://xxx"},"register_code_info":{"register_code":"1111","template_id":"tpl111","state":"state001"}
}返回结果参数说明：access_token  授权方（企业）access_token,最长为512字节
expires_in	授权方（企业）access_token超时时间（秒）
permanent_code	企业微信永久授权码,最长为512字节
auth_corp_info	授权方企业信息
auth_corp_info.corpid	授权方企业微信id
auth_corp_info.corp_name	授权方企业名称，即企业简称
auth_corp_info.corp_type	授权方企业类型，认证号：verified, 注册号：unverified
auth_corp_info.corp_square_logo_url	授权方企业方形头像
auth_corp_info.corp_user_max	授权方企业用户规模
auth_corp_info.corp_agent_max	授权方企业应用数上限
auth_corp_info.corp_full_name	授权方企业的主体名称(仅认证或验证过的企业有)，即企业全称。
auth_corp_info.subject_type	企业类型，1. 企业; 2. 政府以及事业单位; 3. 其他组织, 4.团队号
auth_corp_info.verified_end_time	认证到期时间
auth_corp_info.corp_wxqrcode	授权企业在微工作台（原企业号）的二维码，可用于关注微工作台
auth_corp_info.corp_scale	企业规模。当企业未设置该属性时，值为空
auth_corp_info.corp_industry	企业所属行业。当企业未设置该属性时，值为空
auth_corp_info.corp_sub_industry	企业所属子行业。当企业未设置该属性时，值为空
auth_info	授权信息。如果是通讯录应用，且没开启实体应用，是没有该项的。通讯录应用拥有企业通讯录的全部信息读写权限
auth_info.agent	授权的应用信息，注意是一个数组，但仅旧的多应用套件授权时会返回多个agent，对新的单应用授权，永远只返回一个agent
auth_info.agent.agentid	授权方应用id
auth_info.agent.name	授权方应用名字
auth_info.agent.square_logo_url	授权方应用方形头像
auth_info.agent.round_logo_url	授权方应用圆形头像
auth_info.agent.appid	旧的多应用套件中的对应应用id，新开发者请忽略
auth_info.agent.auth_mode	授权模式，0为管理员授权；1为成员授权
auth_info.agent.is_customized_app	是否为代开发自建应用
auth_info.agent.privilege	应用对应的权限
auth_info.agent.privilege.allow_party	应用可见范围（部门）
auth_info.agent.privilege.allow_tag	应用可见范围（标签）
auth_info.agent.privilege.allow_user	应用可见范围（成员）
auth_info.agent.privilege.extra_party	额外通讯录（部门）
auth_info.agent.privilege.extra_user	额外通讯录（成员）
auth_info.agent.privilege.extra_tag	额外通讯录（标签）
auth_info.agent.privilege.level	权限等级。
1:通讯录基本信息只读
2:通讯录全部信息只读
3:通讯录全部信息读写
4:单个基本信息只读
5:通讯录全部信息只写
auth_info.agent.shared_from	共享了应用的互联企业信息，仅当由互联的企业共享应用触发的安装时才返回
auth_info.agent.shared_from.corpid	共享了应用的互联企业信息，仅当由互联的企业共享应用触发的安装时才返回
auth_user_info	授权管理员的信息，可能不返回（企业互联由上级企业共享第三方应用给下级时，不返回授权的管理员信息）
auth_user_info.userid	授权管理员的userid，可能为空（企业互联由上级企业共享第三方应用给下级时，不返回授权的管理员信息）
auth_user_info.open_userid	授权管理员的open_userid，可能为空（企业互联由上级企业共享第三方应用给下级时，不返回授权的管理员信息）
auth_user_info.name	授权管理员的name，可能为空（企业互联由上级企业共享第三方应用给下级时，不返回授权的管理员信息）
auth_user_info.avatar	授权管理员的头像url，可能为空（企业互联由上级企业共享第三方应用给下级时，不返回授权的管理员信息）
dealer_corp_info	代理服务商企业信息。应用被代理后才有该信息
dealer_corp_info.corpid	代理服务商企业微信id
dealer_corp_info.corp_name	代理服务商企业微信名称
register_code_info	推广二维码安装相关信息，扫推广二维码安装时返回。（注：无论企业是否新注册，只要通过扫推广二维码安装，都会返回该字段）
register_code_info.register_code	注册码
register_code_info.template_id	推广包ID
register_code_info.state	仅当获取注册码指定该字段时才返回