企业微信第三方开发课程 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必填应用的secretsuite_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 企业的suiteIDpre_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_tokenpre_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授权方企业微信idauth_corp_info.corp_name授权方企业名称，即企业简称auth_corp_info.corp_type授权方企业类型，认证号：verified, 注册号：unverifiedauth_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，对新的单应用授权，永远只返回一个agentauth_info.agent.agentid授权方应用idauth_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代理服务商企业微信iddealer_corp_info.corp_name代理服务商企业微信名称register_code_info推广二维码安装相关信息，扫推广二维码安装时返回。（注：无论企业是否新注册，只要通过扫推广二维码安装，都会返回该字段）register_code_info.register_code注册码register_code_info.template_id推广包IDregister_code_info.state仅当获取注册码指定该字段时才返回