企业微信unionid

第三方应用开发

服务端API

开发指南

unionid与external_userid的关联

unionid与external_userid的关联

最后更新：2022/09/16

目录

1. 在服务商在微信侧获取unionid后，可通过unionid查询external_userid，如果微信用户还不是企业的客户，则返回一个pending_id，该 pending_id 90 天内有效。
2. 90天内微信用户成为企业客户时，包括成为企业微信外部联系人和进入企业微信客户群，均可通过接口「external_userid查询pending_id」关联查询过的unionid。

推荐的适配方案

服务商可根据查询结果建立并存储ID映射库：

1. 当微信用户进入小程序等微信服务时，获取openid和unionid后，通过转换接口「unionid查询external_userid」查询并记录ID映射关系，不需要反复查询。包括：
   · unionid → external_userid
   · unionid → pending_id
2. 当客户企业新增客户时，包括成为企业微信外部联系人和进入企业微信客户群，可通过接口「external_userid查询pending_id」立即关联到查询过的unionid，并更新ID映射：
   · unionID → pending_id ← external_userid

当微信用户进入服务商的小程序或公众号时，服务商可通过此接口，将微信客户的unionid转为第三方主体的external_userid，若该微信用户尚未成为企业的客户，则返回pending_id。
小程序或公众号的主体名称可以是企业的，也可以是服务商的。
该接口有调用频率限制，按企业作如下的限制：10万次/小时、48万次/天、750万次/月

请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/idconvert/unionid_to_external_userid?access_token=ACCESS_TOKEN

请求参数：

{
  "unionid":"oAAAAAAA",
  "openid":"oBBBB",
  "subject_type":1
}

参数说明：

权限说明：

当前授权企业必须已认证或已验证
unionid（即微信开放平台账号主体）与openid（即小程序或服务号账号主体）需要认证，且主体名称需与当前授权企业的主体名称一致（查看由服务商代注册的开放平台帐号认证流程），或者主体名称需与服务商的主体名称一致。
openid与unionid必须是在同一个小程序获取到的

返回结果：

｛
 "errcode":0,
 "errmsg":"ok",
 "external_userid":"ooAAAAAAAAAAA",
 "pending_id":"ooBBBBBB"
｝

参数说明：

注：
1. pending_id仅用于关联unionid与external_userid，并无法当成external_userid调用接口。
2. 当微信客户的跟进人或所在客户群的群主不在应用可见范围，也不返回external_userid，而是返回pending_id。

external_userid查询pending_id

该接口可用于当一个微信用户成为企业客户前已经使用过服务商服务（服务商侧曾经调用过unionid转换为第三方external_userid）的场景。本接口获取到的pending_id可以维持unionid和external_userid的关联关系。pending_id有效期为90天，超过有效期之后，将无法通过该接口将external_userid换取对应的pending_id。

请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/idconvert/batch/external_userid_to_pending_id?access_token=ACCESS_TOKEN

请求参数：

{
  "chat_id":"xxxxxx",
  "external_userid":["oAAAAAAA", "oBBBBB"]
}

参数说明：

权限说明：

仅认证企业可调用
该客户的跟进人或其所在客户群群主必须在应用的可见范围之内

返回结果：

｛
 "errcode":0,
 "errmsg":"ok",
 "result":[
 {
	"external_userid":"oAAAAAAA",
 	"pending_id":"pAAAAA"
 },
 {
 	"external_userid":"oBBBBB",
 	"pending_id":"pBBBBB"
 }
 ]
｝

参数说明：

本节内容

• 推荐的适配方案
• unionid转换为第三方external_userid
• external_userid查询pending_id