企业微信第三方开发课程 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    仅当获取注册码指定该字段时才返回

企业微信url及生成授权链接相关推荐

企业微信开发H5页面授权使用接口的问题
企业微信 h5踩坑指南企业微信开发H5页面授权使用接口的问题开发企业微信的时候 h5页面需要获取登录用户的信息,这个时候就需要jsdk里面的 [开发文档] (https://work.weixi ...
微信URL Scheme码+长链接转短链接+短链接通过h5页面跳转到微信小程序
微信URL Scheme码+长链接转短链接+短链接通过h5页面跳转到微信小程序 --生成微信URL Scheme码-->长链接转换成短链接-->通过短信进行推广-->用户访问营销短信 ...
企业微信+esaywechat 扫码授权登录
企业微信+esaywechat 扫码授权登录相关相关这里用的是 Yii2 框架. 安装easywechat: composer require overtrue/wechat:~4.0 -vvv ...
企业微信事件接收服务器,授权通知事件
[TOC] 授权成功通知从企业微信应用市场发起授权时,企业微信后台会推送授权成功通知. 从第三方服务商网站发起的应用授权流程,由于授权完成时会跳转第三方服务商管理后台,因此不会通过此接口向第三方服务 ...
企业微信小程序_授权登录接口获取用户userid
文章目录一.前置知识 1. 阅读企业微信小程序开发文档 2. 企业微信小程序登录流程 3. 微信小程序区别二.前端部分 2.1. 调用登录接口 2.2. 请求后端接口 2.3. 项目源码三.后 ...
企业微信欢迎语如何将链接转换为图文卡片形式？
企业微信支持配置欢迎语,这样客户添加您的企业微信后即可自动推送文字或者链接/图片等,但是推送的链接可能展示不好,本教程讲解如何使用 [小狐工具箱]箱将欢迎语链接转为图文卡片: 企业微信卡片制作教程如下 ...
Node.JS调用企业微信API：生成渠道二维码
目标: 通过API设置成员的"联系我"方式生成渠道标识二维码,实现标记客户扫码渠道,方便个渠道客户信息统计等. 实现环境: 白码低代码平台(该平台提供企业微信API,可直接调用,减 ...
关于企业微信代开发网页授权问题（OAuth2）
PHP版本:7.4 使用框架:tp5.1 easy WeChat插件版本:4.3 获取基本信息获取基本信息(姓名:部门名:职务:座机:对外职务:对外属性:拓展属性:)这些直接使用自建应用授权即可, ...
企业微信自建应用授权登录demo
<?php /*** Created by PhpStorm.* User: liubao* Date: 2018/8/29 更新时间v1:2018-9-29 v1.1:2020-08-10* ...
企业微信第三方应用开发授权设置（PHP版）
开发之前一定要搞明白,企业微信不是企业微信号,虽然有相似之处,但不尽相同!!! 企业微信第三方应用与企业微信自建应用也不相同,一定要区分! !! 本地测试完成,没问题了,直接提交上线,就OK啦!!! ...

企业微信url及生成授权链接