在企业微信中如何获取unionId？

1.概念科普

微信开放和公众平台的定位

• 微信开放平台是为了让第三方应用投入微信的怀抱而设计的，比如第三方的移动应用(Android/IOS)、网站等；微信为了开疆拓土，扩大自己的影响力。
• 微信公众平台是为了让程序员利用微信生态技术开发公众号、小程序而建立的，是一个技术提供平台；这才是微信开发生态起家的根据地，基于此，逐步发展壮大。

appId，openId, unionId三者的区别

• appId

  appId是微信生态应用的唯一标识，在微信开放平台和微信公众平台注册应用，都能获得appId。

通过微信公众平台注册一个公众号A，公众号A就会获得一个应用唯一标识appId_A

通过微信公众平台注册一个小程序B，小程序B就会获得一个应用唯一标识appId_B

通过微信开放平台注册一个移动应用C，移动应用C就会获得一个应用唯一标识appId_C

• openId

微信公众号和小程序都是在微信公众平台管理的,为了识别用户，每个微信公众号或小程序会给用户生成一个openId。 接着上面的例子说，公司在微信公众平台注册了一个小程序A和一个公众号B，那么一个微信用户A在小程序A和公众号B的openId分别为

微信用户A在公众号A中的openId为openId_A

微信用户A在小程序B中的openId为openId_B

• unionId

微信开放平台是用来管理移动应用, 网站应用，公众号，第三方应用(给别的公司开发小程序和公众号)的, 为了识别不同应用之间用户的唯一性。微信开放平台给每个微信用户生成了唯一的标识unionId。由于这些应用是绑定在开放平台下的，所以开放平台还会为哪些没有微信用户openId的应用类型(如移动应用,网站应用)生成openId, 还是套用上面的例子,将appId,openId,unionId串起来就是

微信用户A在公众号A (appid_A) 中的身份标识openId是openId_A, unionId是 unionId_A

微信用户A在小程序B (appid_B) 中的身份标识openId是openId_B, unionId是 unionId_A

微信用户A在移动应用C(appid_C)中的的身份标识openId是openId_C, unionId是 unionId_A

说到这里，你可能会比较好奇，移动应用(Android/IOS)，网站应用为什么要接入微信开放平台，其实官方的宣传已经说得清清楚楚,明明白白。看下图红框中的文字。

2. 如何在企业微信中获取微信用户的unionId?

2.1 为什么要在企业微信中获取unionId?

前面讲了同一个用户对于同一个微信开放平台下的不同应用unionid的用途。对于企业微信，也是同理。如果企微中没有unionid,一个企业有一个小程序，客户既在微信中使用了，也在企微中使用了，会被认为是同一企业下的两个客户。按照常理, 同一个微信用户在同一个公司主体下的所有微信生态产品中，身份应该有一个唯一的标识，一个客户使用了一个企业的微信小程序或是公众号，又同时添加了企业微信，那么这个微信客户在同一个主体企业下的多个小程序和公众号应用中，不能被认为是多个客户。企微中的unionid就是用来标识同一个企微的多个微信小程序和公众号微信客户的唯一身份。仅从unionid这一点来说，企业微信相当于一个功能缩小版的微信开放平台，与微信开发平台相比，仅支持打通同一个企业主体下的微信小程序与公众号。

2.2 登陆企微管理后台，绑定公众号或微信小程序开发者ID

管理员扫码登陆企微管理后台,切换到客户与上下游tab下，点击API,会显示微信开发者ID-绑定操作入口。笔者已经绑定过了，所以显示的是解除绑定操作按钮。

点击绑定按钮后,会跳转到微信公众平台要求扫码进行绑定公众号。需要注意的是,绑定时必须选择与企微账号同主体的公众号，如果主体未认证或不一致，则会提示无法进行绑定。

2.3 调用服务端–获取用户详情接口

接口文档路径： 企业内部开发–服务端API–客户联系–客户管理–获取用户详情

请求方式： GET（HTTPS）
请求地址： https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get?access_token=ACCESS_TOKEN&external_userid=EXTERNAL_USERID&cursor=CURSOR

返回数据：

{
	"errcode": 0,
	"errmsg": "ok",
	"external_contact":{
        "external_userid":"woAJ2GCAAAXtWyujaWJHDDGi0mACHAAA",
        "name":"李四",
        "position":"Manager",
        "avatar":"http://p.qlogo.cn/bizmail/IcsdgagqefergqerhewSdage/0",
        "corp_name":"腾讯",
        "corp_full_name":"腾讯科技有限公司",
        "type":2,
        "gender":1,
        "unionid":"ozynqsulJFCZ2z1aYeS8h-nuasdAAA",
        "external_profile":{}
    },
    "follow_user":[],
    "next_cursor":"NEXT_CURSOR"
}

获取unionid的限制条件,客户必须是微信客户,第三方不能获取。 获取用户详情返回数据中，有我们需要的unionid, 可有一个问题，从接口请求地址可以看出，需要三个参数，其中access_token是公共参数，cursor参数是人数多于500时才需传值，而外部联系人external_userid这个参数，获取比较费事。

2.4 在企微客户端调用getCurExternalContact JS-SDK获取external_userid

所有需要使用JS-SDK的页面必须先注入配置信息，否则将无法调用JS-SDK，wx.config需要传递的参数signature获取需要四步:

1. 使用appId和appSecret获取access_token；
2. 使用access_token获取jsapi_ticket ；
3. 用时间戳、随机数、jsapi_ticket和要访问的url按照签名算法拼接字符串；
4. 对第三步的字符串进行SHA1加密，得到签名。

细节请参考JS-SDK使用权限签名算法, 这个参数时效性是2小时，一般在后端实现签名参数逻辑。

wx.config({
  beta: true,// 有wx.invoke调用形式的jsapi，这个参数要设置成true
  debug: true, // 开启调试模式，调试通过之后要设置成false。
  appld: 'wwa77dc796ae73feaa', // 必填，企业微信的corpID
  timestamp: '1648630619', // 必填，生成签名的时间靓
  nonceStr: 'Wm3WZYTPz0wzccnW', // 必填，生成签名的随机串
  signature: 'eebbd49ce2470bb8874d9705239fa7e0b45f6ff0', // 必填，签名，
  jsApiList: ['getCurExternalContact'] // 必填，需要使用的JS接口列表，凡是要调用的接口都需要传进来
});

通过agentConfig注入自建应用的调用权限，wx.config与wx.agentConfig的签名计算是不一致的，config参与签名计算的tikcet获取接口是https://qyapi.weixin.qq.com/cgi-bin/get_jsapi_ticket?access_token=ACCESS_TOKEN，agentconfig参与签名计算的ticket的获取接口是https://qyapi.weixin.qq.com/cgi-bin/ticket/get?access_token=ACCESS_TOKEN&type=agent_config，两个的签名是不同的。wx.config和wx.agentConfig的其它差别参见 企微官方文档

wx.agentConfig({
  corpid: 'lwwa77dc796ae73feaa', // 必填，企业微信的corpid,必须与当前登录的企业一致
  agentid: '1000010', // 必填，企业微信的应用id 
  timestamp: '1648630619', //必填，生成签名的时间戳
  nonceStr: 'WmSWZYTPzOwzccnW', // 必填，生成签名的随机串
  signature: 'be91b8822fIf8525694458714c31eaddelbbd272', // 必填，签名
  jsApiList: ['getCurExternalContact'], // 必填，传入需要使用的接口名称 
  success: function(res){
    callback(res);
  },
  // ...
 });

调用getCurExternalContact获取外部联系人id，需要注意的是，目前支持的入口有限,好在外部单聊工具栏配置的h5应用页面(如下图所示)可以使用，通过工作台进入h5应用页面无法调用此接口。

wx.invoke('getCurExternalContact', {}, function(res){
  if(res.err_msg == "getCurExternalContact:ok"){
     userId  = res.userId ; //返回当前外部联系人userId
  }else {
    /错误处理
  }
});

把外部联系人externalUserId参数通过接口传递给后端，后端去调用企微服务获取用户详情接口，将unionId返回给前端,前端页面就能判断这个微信用户的唯一性了。

参考文献

• AppID、UnionID 和 OpenID 傻傻分不清楚
• 企业内部开发–服务端API–客户联系–客户管理–获取用户详情
• JS-SDK使用权限签名算法
• 获取当前外部联系人userid