企微自建应用接入

1.简述

QuickAudience(以下简称QA)在对原服务商模式企微接入方式进行了升级，升级为企业自建应用方式接入，升级后，通过企业自建应用接入企微可获得更多企微数据，并不受接口调用次数限制，降低企业获取企微数据成本。

2.接入流程图

由于企微对企业自建应用的接入方式设置了可信IP和域名等安全限制，因此SaaS版的QA产品（企业主体为瓴羊），那么无法直接从企微读取企业客户的数据。为了解决这一问题，企业需要在其内部部署一个QA专用的企微代理，用于获取企微数据并将其转发至QA产品。这一部署方案确保了数据的安全性和完整性，同时满足企业的使用需求。因此需要客户提供回调域名、公网IP等信息，并在客户网络环境内部署QA产品的一方企微代理服务，网络连接示意图如下：

如您存在多品牌在企微认证主体不一致且需要接入QA，可使用同一QA一方企微代理，如下图所示

3.总体接入说明

3.1接入前准备

前期接入准备如下，如您在准备或配置过程中，遇到关于QA产品功能使用方面的问题，请联系产品运营人员，对于配置过程中的技术指导及任何相关疑问，请联系售后支持团队获取帮助。

3.2整体接入流程

4.准备阶段

4.1企微代理服务器资源

4.2企微代理服务器配置

SaaS客户需要部署一方企微代理服务器，QA一方企微代理服务使用Nginx软件实现，对QA与企微的请求进行转发处理，因此需要在服务器（ECS）上安装Nginx软件，并按照模板进行配置，以实现QA请求转发功能。可参考以下步骤进行部署。

4.2.1部署步骤（以CentOS操作系统为例）

安装Nginx服务

sudo yum update 
sudo yum install nginx

启动Nginx

sudo systemctl enable nginx
sudo systemctl start nginx

配置Nginx

cd /etc/nginx/conf.d
vim proxy.conf

配置模板如下：

server {
    listen 80; # 监听端口，如果使用https则为443
    server_name 106.39.X.XX; # 本机的公网IP，【需要修改】
    root /usr/share/nginx/html;
    index index.html index.htm;
  
    # QA请求企微-转发规则配置，用于QA从企微拉取数据、发送企微营销任务等
    location /cgi-bin {
        proxy_pass https://qyapi.weixin.qq.com; # 企微地址，【不需要修改】
    }

    # 企微请求QA-转发规则配置，用于接收企微回调事件
    location / {
        # 【需要修改】QA回调地址，按照QA所在Region进行配置
        # 张北Region：https://quicka.aliyun.com
        # 上海Region：https://quicka-shanghai.aliyun.com
        proxy_pass https://quicka.aliyun.com; 
    }
}

启动Nginx

nginx -t
nginx -s reload

查看日志

tail -f /var/log/nginx/access.log

4.3创建企微自建应用【企微后台】

4.3.1操作路径

企微后台->应用管理->自建->创建应用

4.3.2输入信息

瓴羊logo

4.3.3设置可见范围

4.3.4记录企微应用信息

创建企微自建应用，并获取如下信息，后续配置中使用：

4.4删除服务商代开发模式企微应用

在企微后台，将原有服务商代模式企微应用删除。

4.5QA与企微联通性验证

4.5.1验证企微代理连通性

验证企微代理连通性包含两个方向，QA请求企微方向和企微请求QA方向，验证前需要准备以下信息：

• 企微代理域名，以qawecom.xxx.com为例，实际验证时需要进行替换

• 企微Corpid，以wwb697d33134e48xxx为例 ，实际验证时需要进行替换

• access_token，需要在企微后台获取，https://developer.work.weixin.qq.com/document/path/91039，https://developer.work.weixin.qq.com/devtool/interface/alone?id=15074

验证QA请求企微是否正常

在浏览器中请求http://qawecom.xxx.com/cgi-bin/department/list?access_token=8f7OUcWM8fJGsC41pSwWG8hioA****，检查是否可以正常返回部门信息，errcode为0，errmsg为ok，则说明配置正确。

{
    "errcode": 0,
    "errmsg": "ok",
    "department":[  
    ]
}

验证企微请求QA是否正常

在浏览器中访问https://qawecom.xxx.com/restapi/thirdservice/we/com/inner/event/oneparty/callback/wwb697d33134e48xxx，检查是否能返回，http返回code为200，页面为空白页面，则说明配置正确。

4.5.2验证服务商待开发模式应用已删除

企微服务商应用删除后，5分钟内检查QA产品页面中的企微账号是否已自动删除

4.5.3验证一方企微菜单已开启

一方企微菜单开启后，在营销账号中会展现“企业微信”，如果未开启成功，则没有显示，需要联系QA产品运营进行开通。

5.配置阶段

以下以企微自建应用名称【瓴羊QA企微应用】进行举例

5.1配置应用可见范围【企微后台】

5.2配置应用可信域名及IP【企微后台】

1. 配置可信域名

   使用企微代理服务器的公网域名

   

2. 设置可信IP

   填写企微代理服务器的出口IP

   重要

   注意，企微代理服务器的出口IP与新申请的公网IP不一定一致，可信IP需要填写出口IP，即请求企微时的出口IP，可咨询企业IT人员获取。

   

   

5.3配置应用相关权限【企微后台】

如果要通过API获取客户信息，需要先配置应用具备获取客户信息权限，否则会导致获取失败

1. 进入客户与上下游

   如下图所示在客户与上下游->客户联系->客户，绑定微信开发者ID

   说明

   如不绑定，会影响客户数据的获取。

   

2. 增加可调用的接口应用

   将【瓴羊QA企微应用】应用勾选

   参考文档：概述 - 文档 - 企业微信开发者中心

   

5.4QA关联企微自建应用【QA产品】

如下图所示菜单路径：配置管理->营销账号->账号授权->选择企业微信

填写如下信息：

信息填写说明：

5.5配置应用回调API信息【企微后台】

1. 进入企微自建应用

   

2. 设置API接收

   

   配置信息说明

   配置项	配置值	说明
   URL	https://{domain}.com/restapi/thirdservice/we/com/inner/event/oneparty/callback/{corpid}	domain使用真实域名进行替换 corpid使用企业corpid替换 示例： https://test.lydaas.com/restapi/thirdservice/we/com/inner/event/oneparty/callback/wwb697d33134e48cfc
   Token	随机获取	需要记录，后续在QA上关联企微账号使用
   EncodingAESKey	随机获取	需要记录，后续在QA上关联企微账号使用

5.6配置验证

1. 企微账号关联验证

   账号管理状态，为授权成功

   

   检查回流开关是否打开

   

2. 企微相关数据表结构

   说明

   配置完成后第二天检查

   

3. 企微相关调度任务

   说明

   配置完成后第二天检查

   

6.运维监控

一方企微代理作为QA与企微通信统一转发的关键组件，一旦发生异常将影响QA产品企微相关功能的使用，如企微数据回流异常、营销活动企微组件发送异常等，因此需要对一方企微代理配置相应监控告警，当出现异常时能及时发现并处理。

建议对如下对象进行配置告警监控规则：

7.其他注意事项

8.FAQ

8.1调用企微接口返回48002

现象

企微错误说明

解决办法

按照5.3企微后台配置权限

8.2 调用企微接口返回一直报502

在配置都没有问题的情况下（域名、可信ip）可以考虑QA的服务器ip是否在代理服务器的安全白名单中，需要开通80和443端口

8.3企微常见错误码

https://developer.work.weixin.qq.com/document/path/96213