说明

1. 本次升级对第三方服务商的影响和推荐兼容方案

2. 本次升级的重点FAQ

概述

为更好地保护企业与用户的数据，企业微信对代开发应用账号相关的ID和敏感信息权限将做全面的升级，涉及的ID有corpid、userid、external_userid与unionid。

基本的原则如下：

1. 企业corpid
   代开发应用获取的corpid不再是明文的corpid，将升级为第三方服务商级别的加密corpid。同一服务商的所有新建代开发应用获取的corpid一致；不同服务商获取的corpid不同。
   
2. 企业员工userid
   代开发应用获取的userid不再是明文的userid，将升级为第三方服务商级别的加密userid。同一服务商的新建代开发应用获取的userid一致；不同服务商获取的userid不同。
   
3. 企业外部联系人external_userid
   代开发应用获取的企业外部联系人external_userid，将升级为第三方服务商与企业级别的加密external_userid，同一服务商的所有新建代开发应用获取的external_userid一致；不同服务商获取的external_userid不同；同一外部联系人，在不同的授权企业下，同一服务商获取的external_userid不同。以上外部联系人包括微信与企业微信联系人。
   
4. 企业客户微信unionid
   代开发应用在获取客户详情时，企业微信将不再返回企业客户的微信unionid。服务商需要在企业客户在微信中使用服务时，根据从微信开放平台获取的unionid与openid，调用企业微信提供的转换接口，查询出对应的微信用户external_userid。

需要开发者重点关注的是，与第三方saas应用不同，本次id升级不区分是否新授权的企业。而是按照应用安装时间回收。2022年6月28日23点59分后， 授权的代开发应用返回的ID都为升级后的ID；对于历史授权的企业，所有接口与回调返回的ID暂时不变，后续再另行通知统一的升级时间，服务商可以提前为历史授权的企业将corpid、userid、external_userid进行转换，转换完成之后再调用设置迁移完成接口迁移到升级后的模式。

一、企业corpid的升级方案

1.1 升级前后对比

假设一个企业的明文corpid是CorpIdA。

1. 授权了服务商A代开发应用和第三方应用
2. 授权了服务商B的代开发应用和第三方应用
3. 自己开发了一个自建应用。
   升级之前，所有代开发应用、自建应用能获取到的corpid均为CorpIdA。
   第三方应用获取到的则是加密过的CorpId，服务商之间相互隔离，示意图如下：
   

升级之后，以服务商A为例，区分是否新安装的代开发应用，如果是新安装的代开发应用，则获取到密文CorpId， 取值等同于以第三方应用名义获取到的CorpId， 示意图如下：

1.2 升级之后的接口变化

所有接口无论是入参，还是返回结果，涉及corpid的字段名皆不变；所有回调事件，涉及corpid的字段名皆不变。
例如，获取企业永久授权码中，corpid字段在升级之后依然保持字段名为corpid。
例如，获取企业凭证中，auth_corpid字段在升级之后依然保持字段名为auth_corpid。
例如，变更授权通知中，AuthCorpId字段依然保持字段名AuthCorpId。
例如，成员关注及取消关注事件中，ToUserName字段在升级之后依然保持字段名为ToUserName。
在一些使用corpid作为url或小程序路径参数时，升级之后，参数名不变，仅需将参数值替换为升级后的ID。例如，微信进入居民上报小程序中，path参数中的strcorpid字段在升级之后依然保持字段名为strcorpid。

【注意】corpid明文不区分大小写，而corpid密文则大小写敏感，故使用corpid的地方，不能再转为纯小写或纯大写。

【重要】从2022年6月20日20点开始，对于新安装的代开发应用，将启用升级后的corpid。第三方应用理论上代码不需要做任何调整，即可兼容升级之后的corpid。

1.3 历史已授权代开发应用方案

对于历史已授权的代开发应用，所有接口与回调返回的corpid仍然为明文corpid。服务商可以调用corpid转换将其转换为密文corpid，再调用设置迁移完成接口将该企业迁移到升级后的模式

1.4 corpid转换

用于将企业主体的corpid转换为服务商的密文corpid，服务商可通过第三方应用和代开发应用调用该接口。

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

请求参数：

{
  "corpid":"xxxxx"
}

参数说明：

权限说明：

仅限第三方服务商，转换已获授权企业的corpid

返回结果：

｛
 "errcode":0,
 "errmsg":"ok",
 "open_corpid":"AAAAAA"
｝

参数说明：

二、企业员工userid的升级方案

2.1 升级前后对比

假设一个企业的明文userid是UserIdA。

1. 授权了服务商A代开发应用和第三方应用
2. 授权了服务商B的代开发应用和第三方应用
3. 自己开发了一个自建应用。
   升级之前，所有代开发应用、自建应用能获取到的userid均为明文UserIdA。
   第三方应用获取到的则是加密过的userid，服务商之间相互隔离，示意图如下：
   

升级之后，以服务商A为例，区分是否新安装的代开发应用，如果是新安装的代开发应用，则获取到密文userid， 取值等同于以第三方应用名义获取到的userid， 示意图如下：

2.2 升级之后的接口变化

所有接口无论是入参，还是返回结果，涉及userid的字段名皆不变；所有回调事件，涉及userid的字段名皆不变。
例如，获取部门成员中，userid字段在升级之后依然保持字段名为userid。
例如，日历接口中，organizer字段在升级之后依然保持字段名为organizer。
例如，成员通知事件中，UserID字段依然保持字段名UserID。
例如，成员关注及取消关注事件中，FromUserName字段在升级之后依然保持字段名为FromUserName。
在一些使用userid作为url或小程序路径参数时，升级之后，参数名不变，仅需将参数值替换为升级后的ID。例如，微信进入居民上报小程序中，path参数中的userid字段在升级之后依然保持字段名为userid。
【注意】userid明文不区分大小写，而userid密文则大小写敏感，故使用userid的地方，不能再转为纯小写或纯大写。

【重要】 从2022年6月20日20点开始，对于新授权的代开发应用，将启用升级后的userid。

2.3 历史已授权代开发应用的方案

对于历史已授权的代开发应用，所有接口与回调返回的userid仍然为明文userid。服务商可以调用userid转换将其转换为密文userid，再调用设置迁移完成接口将该企业迁移到升级后的模式

2.4 userid的转换

用于将企业明文的userid转换为服务商主体加密的open_userid，服务商可通过第三方应用和代开发应用调用该接口。

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

请求参数：

{
  "userid_list":["aaa", "bbb"]
}

参数说明：

权限说明：

仅代开发自建应用或第三方应用可调用
成员需要在应用的可见范围内
请确保传入userid的正确性，若出错的次数较多，会导致1天不可调用，（具体限制阈值由授权企业的员工规模决定）

返回结果：

{
    "errcode": 0,
    "errmsg": "",
    "open_userid_list": [
        {
            "userid": "aaa",
            "open_userid": "xxxxx",
        }
    ],
    "invalid_userid_list":["bbb"]
}

参数说明：

三、企业客户external_userid的升级方案

3.1 升级前后对比

假设一个用户同时属于三家企业的客户，这三家企业分别授权了服务商A与服务商B的应用。
升级之前，属于不同企业的同一个客户：

1. 第三方应用，同一服务商获取到的external_userid不一致，不同服务商获取的external_userid也不一致。
2. 代开发应用，同一个服务商获取到的external_userid一致，不同服务商不一致。
   示意图如下：
   

升级之后，新安装的代开发应用获取的external_userid跟第三方应用获取到的一样，具体如下：

3.2 升级之后的接口变化

所有接口无论是入参，还是返回结果，涉及external_userid的字段名皆不变；所有回调事件，涉及external_userid的字段名皆不变。
例如，获取客户详情中，external_userid字段在升级之后依然保持字段名为external_userid。
例如，企业客户事件中，ExternalUserID字段依然保持字段名ExternalUserID。

【重要】从2022年6月20日20点开始，对于新授权的代开发应用，将启用升级后的external_userid。对于历史已授权的代开发应用，服务商可以调用转换external_userid接口将其转换为升级后的external_userid，再调用设置迁移完成接口将该企业迁移到升级后的模式。

3.2.1 转换external_userid

用于将企业主体的external_userid转换为服务商主体加密的external_userid，服务商可通过第三方应用和代开发应用调用该接口。

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

请求参数：

{
  "external_userid_list":["xxxxx","yyyyyy"]
}

参数说明：

权限说明：

仅代开发自建应用或第三方应用可调用
客户联系和家校场景中，external_userid对应的跟进人需要在应用可见范围内
微信客服场景中，仅支持48小时内客服会话的external_userid

返回结果：

｛
 "errcode":0,
 "errmsg":"ok",
 "items":[
 	{
 		"external_userid":"xxxxx",
 		"new_external_userid":"AAAA"
 	},
 	{
 		"external_userid":"yyyyy",
 		"new_external_userid":"BBBB"
 	}
 ]
｝

如果传入了新的external_userid，则原样返回。

参数说明：

3.2.2 转换客户群成员external_userid

转换external_userid接口不支持客户群的场景，如果需要转换客户群中无好友关系的群成员external_userid，需要调用本接口，调用时需要传入客户群的chat_id。

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

请求参数：

{
  "chat_id":"wrOgQhDgAAMYQiS5ol9G7gK9JVAAAA",
  "external_userid_list":["xxxxx","yyyyyy"]
}

参数说明：

权限说明：

仅代开发自建应用或第三方应用可调用
客户群的群主需要在应用可见范围内

返回结果：

｛
 "errcode":0,
 "errmsg":"ok",
 "items":[
 	{
 		"external_userid":"xxxxx",
 		"new_external_userid":"AAAA"
 	},
 	{
 		"external_userid":"yyyyy",
 		"new_external_userid":"BBBB"
 	}
 ]
｝

如果传入了新的external_userid，则原样返回。

参数说明：

四、企业客户微信unionid的升级方案

为了更好的保护微信用户的隐私，企业微信接口将不再返回企业客户的微信unionid。服务商需要在企业客户在微信中使用服务时，根据从微信开放平台获取的unionid与openid，调用企业微信提供的转换接口，查询出对应的微信用户external_userid。

4.1 升级之后的接口变化

从2022年6月20日20点开始新授权代开发应用不再返回unionid。如果为历史授权企业调用接口设置迁移完成，该企业也将不再返回unionid。

• 获取客户详情
• 批量获取客户详情
• 获取客户群详情
• 获取客户基础信息

4.2 unionid查询external_userid

场景一：用户使用企业主体的小程序或公众号
当微信用户在微信中使用的小程序或公众号是第三方服务商为企业代开发的，其主体为授权的企业，此时可调用企业主体unionid转换为第三方external_userid接口转换为代开发应用升级后的external_userid。

场景二：用户使用第三方主体的小程序或公众号
当微信用户在微信中使用第三方应用的小程序或公众号时，第三方可将获取到的unionid与openid，调用第三方主体unionid转换为第三方external_userid接口转换为企业客户或学生家长的external_userid。

注意：以上两个接口调用频次有限，每个服务商每小时仅可调用5万次，每天仅可调用24万次，应由用户的主动行为来触发查询（例如用户进入小程序时触发），严禁批量进行ID转换，如有发现违规行为，将封禁服务商的接口调用权限。同时对于场景二，建议服务商的小程序路径或公众号页面链接带上corpid参数，如此可明确地转换出该企业对应的external_userid，以获得更好的性能。

五、代开发应用迁移状态

5.1 代开发应用设置迁移完成

服务商完成了代开发应用的新旧id（userid/corpid/external_userid)的迁移，即可主动将该企业设置为“迁移完成”，设置之后，该代开发应用获取到的将是升级后的id。注意，该接口需要使用provider_access_token来调用。

注意：
1. 当该企业同时是服务商， 并对自己授权的情况，无需调用本接口。
2. 设置迁移完成后，接口不再吐出unionid。

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

请求参数：

{  
    "corpid":"xxxxx",
    "agentid":1111,
    "openid_type":[
        1,3
    ]
}

参数说明：

注：
1.userid与corpid只能同时设置为升级模式，external_userid可以单独升级。
2.此接口还可为第三方应用设置迁移完成状态，若只传入正确corpid，未传入代开发应用agentid，则视为：更新该企业下同服务商所有第三方应用的对应升级状态。

权限说明：

该企业授权了该服务商代开发应用

返回结果：

｛
 "errcode":0,
 "errmsg":"ok"
｝

参数说明：

5.2 代开发应用查询迁移状态

新授权代开发应用或代开发应用设置迁移完成后，均可能会返回新的openid，服务商可使用此接口查询回收状态，注意与设置迁移完成接口不同，该接口需要使用应用access_token来调用。

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

参数说明：

权限说明：

仅代开发自建应用和第三方应用可以调用

返回结果：

{
   "errcode": 0,
   "errmsg": "",
   "migration_info" :
   [
       {
           "openid_type": 1,
           "status": 0
       },
       {
           "openid_type": 3,
           "status": 1
       }
   ]
}

参数说明：

六、成员敏感信息权限升级

6.1. 升级后的变化

升级后，2022年6月20日20点起，新授权的代开发应用，成员信息权限调整为成员基本信息和成员敏感信息。

6.1.1 成员基本信息

企业管理员确认后，可通过接口直接获取成员基本信息，包括：姓名、部门名、职务、座机、对外职务、对外属性和拓展属性。
相关接口：读取成员、获取部门成员详情、导出成员详情

6.1.2 成员敏感信息

企业管理员确认且员工手动授权后，可获取个人敏感信息，包括：头像、性别、手机号、邮箱、企业邮箱、地址和员工企业微信二维码。

注意：企业管理员确认后，并不能通过通讯录接口直接获取到成员敏感信息，需要成员在oauth2授权登录时，通过「获取访问用户敏感信息」接口获取。

6.2 历史已授权代开发应用方案

历史已授权的代开发应用，成员敏感信息权限暂时保持不变，服务商可继续调用通讯录接口获取员工敏感信息。

七、本次升级对第三方服务商的影响及建议兼容方案

1. 企业微信应用对接

从2022 年6月28日23点开始，所有代开发应用将返回服务商主体加密的corpid、userid和external_userid，且无法直接通过后台接口获取手机号等敏感信息。

推荐方案：
基于企业微信开发时，存在三种 “应用对接场景”：

1. 企业和服务商应用对接
   企业的内部应用如会话内容存档等，需要与服务商新授权的代开发应用对接。企业可通过「自建应用ID转换接口」，将服务商主体加密的ID转换为企业主体对应的ID。
   
2. 服务商之间的应用对接
   服务商可在「服务商助手 – 接口广场」中开放自己应用的接口，也可调用其他服务商应用的接口，接口广场会自动转换不同服务商所对应的ID。
   
3. 服务商已有系统与企业微信的应用对接
   服务商可使用以下转换接口进行账号匹配：
   1）通过手机号获取第三方服务商主体下的userid
   2）通过邮箱获取第三方服务商主体下的userid
   3）通过明文userid获取第三方服务商主体下的userid

2. 微信unionid和企业微信external_userid关联

代开发应用将无法通过接口从企业微信获取客户 unionid（如果代开发应用没有依赖 unionid，则无影响）。

推荐方案：

• 服务商在微信侧获取unionid后，可通过 unionid查询external_userid。如果微信用户还不是企业的客户，则返回一个pending_id，该 pending_id 90 天内有效。
  
• 90天内微信用户成为企业客户时，包括成为企业微信外部联系人和进入企业微信客户群，均可通过接口「external_userid查询pending_id」关联查询过的unionid。
  
• 在客户联系场景中，第三方应用在微信里获取到用户身份之后，可使用 「联系我」接口动态生成二维码或者小程序按钮，用户添加之后即可实现关联。同理，在微信客服场景中，可使用获取客服账号链接动态生成链接，以此实现关联。

3. 敏感信息需成员主动授权

新授权的代开发应用，不能直接通过接口直接获取包括邮箱、手机号在内的员工敏感信息。企业管理员确认后，需要成员在oauth2登录时主动授权。

推荐方案：
企业微信内应用登录的身份标识，应基于无需用户授权的第三方服务商主体下的userid，并实现应用的基本功能。在此基础上，应用可基于合理必要的场景，向用户申请敏感信息授权。

4. 服务商需通过第三方应用或代开发应用提供服务

• 2022年6月20日起，新开启的通讯录同步和新创建的自建应用需配置企业可信IP，且不可配置第三方服务商的IP。
• 历史已开启的通讯录同步暂无需配置企业可信IP，但不允许新增的服务商IP调用接口，调用时会报错，错误码为60020。

推荐方案：
第三方服务商不可通过企业自建应用及企业“管理工具 - 通讯录同步”的secret违规获取企业通讯录数据，服务商需要通过第三方应用或代开发应用为企业开发应用。

FAQ

1. 6月20日至6月28日灰度期间，如何确认授权的代开发应用账号ID已升级？
   答：灰度期间授权的代开发应用，ID体系默认不升级，即返回企业主体ID。服务商可调用设置迁移完成接口，将应用切换为升级后的ID模式。6月28日起授权的代开发应用均为升级后ID模式。
   
   
2. 6月28日前，如何测试代开发升级后的ID方案？
   答：如果已授权的代开发应用未升级，可以调用设置迁移完成接口迁移到升级后的模式。注意，迁移到升级完成是不可回退的，所以请使用测试企业进行测试。
   
   
3. 代开发应用ID升级是企业维度还是应用维度？
   答：应用维度。2022年6月28日23点后，新授权的代开发应用都将返回服务商主体加密的ID，且不返回UnionID。若客户企业取消历史授权的代开发应用后重新授权，则也返回升级后的ID。
   
   
4. 代开发应用ID升级后，返回的服务商主体加密的ID与第三方应用是否一致？
   答：一致。针对同一服务商名下所有第三方应用和代开发应用获取的加密ID，保持一致。
   
   
5. 代开发应用如何获取员工的敏感信息？
   答：按照代开发应用的授权时间：
   • 从6月20日起所有新授权的代开发应用，企业管理员确认后，成员在登录应用时自主授权敏感信息。服务商可通过「获取访问用户敏感信息」接口获取。
   • 6月20日前已授权的代开发应用，敏感信息获取方式不变，企业管理员确认后，调用通讯录接口获取员工敏感信息。
     
     
6. 代开发账号ID升级全量发布后，是否会影响到历史已有的代开发应用？
   答：不会影响。代开发ID升级仅面向新授权的代开发应用，不会影响历史授权的代开发应用。
   历史已授权的代开发应用：
   • 所有接口与回调返回的ID保持不变。服务商可调用设置迁移完成接口，将历史应用切换为升级后的ID模式。
   • 敏感信息获取方式不变，可继续调用通讯录接口获取员工敏感信息。
     
     
7. 代开发账号ID升级后，企业内部应用如何与服务商应用对接？
   答：企业内部开发时，通过会话内容存档、客户联系、自建应用等内部secret获取的ID与服务商ID不同。而企业的内部应用在一些场景下需要与第三方服务商的应用对接。为此，企业微信提供了「自建应用ID转换」接口，支持企业将第三方应用或代开发应用获取的userid和external_userid转换为企业主体对应的ID，以此实现应用对接。
   
   
8. 历史已经开启的通讯录同步是否需要配置“企业可信IP”？
   答：不需要，但是不允许新增的服务商IP调用接口。
   • 6月20日前已经开启的通讯录同步，暂时无需配置“企业可信IP”，历史已访问过的IP可继续调用接口。但是不允许新增的服务商IP调用接口，调用时会报错，错误码为60020。
   • 若6月20日关闭后重新开启，则需配置“企业可信IP”，且不可配置第三方服务商的IP。
     
     
9. 员工敏感信息授权时，有效期内如何引导用户调整权限？
   答：当通过oauth2发起员工敏感信息授权时，为避免打扰用户，在30天内仅会出现一次授权页。有效期内，可引导用户进入“应用详情页 – 个人敏感信息授权管理” 中重新勾选。
   
   
10. 调用jsapi时传入升级后的userid与external_userid，提示不合法，原因是什么？
    答：首先确认用户的企业微信终端已更新到最新版本，其次确认调用该jsapi之前，是否有成功调用wx.agentConfig，部分旧的jsapi之前只需要调用wx.config即可，但wx.config之后没有应用身份，无法准确解出userid与external_userid，故ID升级之后要求调用wx.agentConfig.