企业内部开发

企业内部开发流程.png

开发第三方应用

一、三种token

https://work.weixin.qq.com/api/doc#11791

企业接口的token：access_token

以企业的corpid和永久授权码来获取access_token
为企业开放的所有接口，都需要access_token参数【调用通讯录，应用，消息等接口】
获取方法
- 第三方服务商在取得企业的永久授权码之后，调用接口

请求方式：POST（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/service/get_corp_token?suite_access_token=SUITE_ACCESS_TOKEN
// 请求包体
 {
     "auth_corpid": "auth_corpid_value",  【必传：授权方corpid】
     "permanent_code": "code_value" 【必传，永久授权码，通过get_peremanent_code获取】
 }
// 返回结果
{
    "errcode":0 ,
    "errmsg":"ok" ,
    "access_token": "xxxxxx",   【授权方（企业）access_token，最长512字节】
    "expires_in": 7200 【授权方（企业）access_token 超时时间】
}

应用授权的token：suited_access_token

企业在授权应用时，第三方需要以suite_id（第三方应用id），suite_secret（第三方应用密钥）换取suite_access_token，再以suite_access_token访问应用授权的接口。
在最终访问授权企业的接口时，再将suite_access_token换为企业的access_token

服务商的token： provider_access_token

以corpid，provider_secret换取provider_access_token，代表的是服务商的身份，与应用无关。

请求方式：POST（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/service/get_provider_token
// 请求包体
 {
    "corpid":"xxxxx",              // 服务商的corpid
    "provider_secret":"xxx"    // 服务商的secret，在服务上后台通用开发参数可查看
 }

// 返回结果
 {
    "errcode":0 ,
    "errmsg":"ok" ,
    "provider_access_token":"enLSZ5xxxxxxJRL",  // 服务商的access_token，最长512字节
    "expires_in":7200   // provider_access_token 有效期（秒）
 }

企业微信开发流程

术语

corpid：每个企业都有唯一的corpid：我的企业--企业信息
userid：每个成员都有唯一的userid（账号）：通讯录--成员详情页
部门id：每个部门都有唯一的id：通讯录-组织架构-部门右边的小圆点
-tagid：每个标签都有唯一的标签id：通讯录-标签
agentid：每个应用唯一的id：应用与小程序-应用详情页
secret：企业应用中用于保障数据安全的钥匙【跟agentid配套】，目前的secret：
- 自建应用secret：应用与小程序--应用--自建--某应用
- 基础应用secret：【如审批，打卡等应用】企业与小程序--应用--基础--某应用--点开API小按钮
- 通讯录管理secret：通讯录同步【需开启api接口同步】
- 外部联系人管理secret：外部联系人--点开API小按钮
access_token：是企业后台去企业微信的后台获取信息时的重要票据，由corpid和secret产生。所有接口在通信时都需要携带access_token用于验证接口的访问权限

开发步骤

https://work.weixin.qq.com/api/doc#10013/%E6%9C%AF%E8%AF%AD%E4%BB%8B%E7%BB%8D

1、获取secret
通讯录管理，外部联系人管理，审批，打卡等基础应用是企业微信默认集成的应用，可以直接开启并拿到secret

2、开启接收消息模式（可选）
以下功能需要提前开启消息接收模式

获取企业成员的地理位置信息
动态调整企业应用的的信息
获取企业成员点击事件类型的应用菜单行为
获取企业成员通过应用给企业后台发送的消息

3、获取access_token：gettoken方法

请求方式：GET（HTTPS）
请求URL：https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRECT
每个应用有独立的secret，所以每个应用的access_token应该分开来获取【区分应用存储】
返回结果：
{
   "errcode":0， // errcode=0：调用成功
   "errmsg":""，
   "access_token": "accesstoken000001", // 存储时至少保留512字节的存储空间
   "expires_in": 7200  // access_token有效时长
}

4、缓存和刷新access_token
开发者需要缓存access_token用于后续接口的调用【不能频繁调用gettoken接口，否则会受到频繁拦截】
当access_token失效或过期时，需要重新获取
5、开发应用逻辑
6、回调配置

回调配置

1、什么时候需要回调服务？
在集成企业微信与内部系统时，我们需要搭建一个回调服务来实现以下功能：

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

2、回调服务需要哪些配置？
配置回调服务，需要三个配置项，分别是：URL，Token，EncodingASEKey
https://work.weixin.qq.com/api/doc#90000/90135/90930/3.%20%E5%9B%9E%E8%B0%83%E6%9C%8D%E5%8A%A1%E9%9C%80%E8%A6%81%E5%AE%9E%E7%8E%B0%E5%93%AA%E4%BA%9B%E5%8A%9F%E8%83%BD
（1）URL【回调服务地址】：由开发者搭建，用于接收通知消息或事件。需要同时支持HttpGet和HttpPost两种能力

回调URL能力.png

*** 回调服务需要实现哪些功能？

支持Http Get请求验证URL有效性

// 企业管理员在配置完回调url信息时，企业微信会发送一条验证消息到该url中
请求方式：GET
请求地址：http://xxx.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS×tamp=13500001234&nonce=123412323&echostr=ENCRYPT_STR
参数说明：
msg_signature: 企业微信加密签名，msg_signature计算结合了企业填写的token，请求中的timestamp，nonce，解密的消息体
【消息体签名检验：https://work.weixin.qq.com/api/doc#90000/90139/90968/%E6%B6%88%E6%81%AF%E4%BD%93%E7%AD%BE%E5%90%8D%E6%A0%A1%E9%AA%8C】
timestamp：时间戳，与nonce结合使用，用于防止请求重放攻击
nonce：随机数，与timestamp结合使用，防止请求重放攻击
echostr：加密的字符串，需要解密得到消息内容明文，解密后有random，msg_len，msg（消息内容明文），receiveid四个字段
【解密得到消息内容明文方法：https://work.weixin.qq.com/api/doc#90000/90139/90968/%E5%AF%86%E6%96%87%E8%A7%A3%E5%AF%86%E5%BE%97%E5%88%B0msg%E7%9A%84%E8%BF%87%E7%A8%8B】

支持Http post请求接收业务数据

请求方式：post
请求地址：http://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS×tamp=13500001234&nonce=123412323
接收数据格式：
 
   
   
   

参数说明：
toUserName：企业微信的CorpId，当为第三方应用回调事件时，Corpid的内容为suiteid
AgentID：接收的应用id，可在应用的设置页面获取。仅应用相关的回调会带该字段
encrypt：消息结构体加密后的字符串

获取企业微信服务器的ip段

// 企业微信在回调企业指定的url时，是通过特定ip发送出去的。如果企业需要做防火墙配置，那么可以通过下面的接口获取到所有相关的ip段
请求方式：get（https）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/getcallbackip?access_token=ACCESS_TOKEN
参数说明：
access_token：接口调用凭证
返回结果：
{
    "errcode": 0,
    "errmsg": "ok",
    "ip_list": ["101.226.103.*", "101.226.62.*"]   // 企业微信回调的ip段
}

（2）token：用于计算签名

回调配置-token.png

（3）EncodingASEKey：用于消息内容加密

回调配置--EncodingASEKey.png

企业微信开发