登录
基础
连接微信
办公目录
为更好地保护企业与用户的数据，企业微信对账号相关的ID将做全面的升级，涉及的ID有corpid、userid、external_userid与unionid。基本的原则如下：
需要开发者重点关注的是，对于新授权的企业，返回的ID都为升级后的ID；对于历史授权的企业，每种ID的过渡兼容方案有所不同。
新授权企业的定义如下：未授权过服务商的任一应用；曾经授权过，但全部取消授权之后再重新授权。（若当前已授权服务商的应用，再增加授权同一服务商的其他应用，则视为历史授权企业。）
假设一个企业的明文corpid是CorpIdA，分别授权了服务商A与服务商B的两个应用，升级之前，所有应用能获取到的corpid均为CorpIdA，如下：
升级之后，服务商A与服务商B名下应用可以获取到的corpid分别为CorpIdA1， CorpIdA2。自建应用仍保持为CorpIdA。
所有接口无论是入参，还是返回结果，涉及corpid的字段名皆不变；所有回调事件，涉及corpid的字段名皆不变。
例如，获取企业永久授权码中，corpid字段在升级之后依然保持字段名为corpid。
例如，获取企业凭证中，auth_corpid字段在升级之后依然保持字段名为auth_corpid。
例如，变更授权通知中，AuthCorpId字段依然保持字段名AuthCorpId。
例如，成员关注及取消关注事件中，ToUserName字段在升级之后依然保持字段名为ToUserName。
在一些使用corpid作为url或小程序路径参数时，升级之后，参数名不变，仅需将参数值替换为升级后的ID。例如，微信进入居民上报小程序中，path参数中的strcorpid字段在升级之后依然保持字段名为strcorpid。
【注意】corpid明文不区分大小写，而corpid密文则大小写敏感，故使用corpid的地方，不能再转为纯小写或纯大写。
【重要】从2021年11月17号开始，对于新授权的企业，将启用升级后的corpid。第三方应用理论上代码不需要做任何调整，即可兼容升级之后的corpid。
对于历史已授权的企业，所有接口与回调返回的corpid仍然为明文corpid，暂无须整改。
将明文corpid转换为第三方应用获取的corpid
请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/service/corpid_to_opencorpid?provider_access_token=ACCESS_TOKEN
请求参数：
{
"corpid":"xxxxx"
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| provider_access_token | 是 | 应用服务商的provider_access_token，获取方法参见服务商的凭证 |
| corpid | 是 | 待获取的企业ID |
权限说明：
仅限第三方服务商，转换已获授权企业的corpid
返回结果：
｛
"errcode":0,
"errmsg":"ok",
"open_corpid":"AAAAAA"
｝参数说明：
| 参数 | 说明 |
|---|---|
| errcode | 返回码 |
| errmsg | 对返回码的文本描述内容 |
| open_corpid | 该服务商第三方应用下的企业ID |
假设一个企业员工的明文userid是UserIdA，企业分别授权了服务商A与服务商B的两个应用，升级之前，所有应用能获取到的userid均为UserIdA，如下：
升级之后，服务商A与服务商B名下应用可以获取到的userid分别为UserIdA1， UserIdA2。自建应用仍保持为UserIdA。
所有接口无论是入参，还是返回结果，涉及userid的字段名皆不变；所有回调事件，涉及userid的字段名皆不变。
例如，获取部门成员中，userid字段在升级之后依然保持字段名为userid。
例如，日历接口中，admin_userid字段在升级之后依然保持字段名为admin_userid。
例如，成员通知事件中，UserID字段依然保持字段名UserID。
例如，成员关注及取消关注事件中，FromUserName字段在升级之后依然保持字段名为FromUserName。
在一些使用userid作为url或小程序路径参数时，升级之后，参数名不变，仅需将参数值替换为升级后的ID。例如，微信进入居民上报小程序中，path参数中的userid字段在升级之后依然保持字段名为userid。
【注意】userid明文不区分大小写，而userid密文则大小写敏感，故使用userid的地方，不能再转为纯小写或纯大写。
【重要】从2021年11月17号开始，对于新授权的企业，将启用升级后的userid。第三方应用理论上代码不需要做任何调整，即可兼容升级之后的userid。
对于历史已授权的企业，所有接口与回调返回的userid仍然为明文userid，暂无须整改。
将自建应用获取的userid转换为第三方应用获取的userid
请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/batch/userid_to_openuserid?access_token=ACCESS_TOKEN
请求参数：
{
"userid_list":["aaa", "bbb"]
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| access_token | 是 | 代开发自建应用或第三方应用的接口凭证 |
| userid_list | 是 | 获取到的成员ID列表，最多不超过1000个 |
权限说明：
仅代开发自建应用或第三方应用可调用
成员需要在应用的可见范围内
请确保传入userid的正确性，若出错的次数较多，会导致1天不可调用，（具体限制阈值由授权企业的员工规模决定）
返回结果：
{
"errcode": 0,
"errmsg": "",
"open_userid_list": [
{
"userid": "aaa",
"open_userid": "sdflajsldjflad"
}
],
"invalid_userid_list":["bbb"]
}参数说明：
| 参数 | 说明 |
|---|---|
| errcode | 返回码 |
| errmsg | 对返回码的文本描述内容 |
| open_userid_list | 该服务商第三方应用下的成员ID |
| open_userid_list.userid | 转换成功的userid |
| open_userid_list.open_userid | 转换成功的userid对应的该服务商应用下的成员ID |
| invalid_userid_list | 转换失败的userid列表 |
假设一个用户同时属于三家企业的客户，这三家企业分别授权了服务商A与服务商B的应用，升级之前，同一个服务商获取到同一个用户的external_userid一致，不同服务商不一致，具体如下：
升级之后，属于不同企业的同一个客户，同一服务商获取到的external_userid不一致，
不同服务商获取的external_userid也不一致，具体如下：
所有接口无论是入参，还是返回结果，涉及external_userid的字段名皆不变；所有回调事件，涉及external_userid的字段名皆不变。
例如，获取客户详情中，external_userid字段在升级之后依然保持字段名为external_userid。
例如，企业客户事件中，ExternalUserID字段依然保持字段名ExternalUserID。
【重要】从2021年11月17号开始，对于新授权的企业，将启用升级后的external_userid。第三方应用理论上代码不需要做任何调整，即可兼容升级之后的external_userid。
【重要】对于历史已授权的企业，在2022年3月1号之前，所有接口与回调返回的external_userid仍然为旧的external_userid，从2022年3月1号0点开始逐步升级历史授权的企业，升级的企业对应的所有输入与返回的external_userid字段，将启用升级后的external_userid。所以服务商需要在此之前完成历史数据的迁移整改。由于涉及历史数据的迁移，需要企业管理员重新授权，具体流程如下：
推送到服务商设置的接收事件回调url上(应用管理-通用开发参数-系统事件接收URL)
请求方式：POST（HTTPS）
请求地址：https://127.0.0.1/service/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608×tamp=1403610513&nonce=380320359
请求包体：
xml请求示例：
<xml>
<AuthCorpId><![CDATA[xxxx]]></AuthCorpId>
<InfoType><![CDATA[agree_external_userid_migration]]></InfoType>
<ServiceCorpId><![CDATA[xxxx]]></ServiceCorpId>
<TimeStamp>1403610513</TimeStamp>
</xml>json请求示例：
{
"AuthCorpId": "xxxx",
"InfoType": "agree_external_userid_migration",
"ServiceCorpId": "xxxx",
"TimeStamp": 1403610513
}服务商的响应必须在1000ms内完成
参数说明：
| 参数 | 说明 |
|---|---|
| AuthCorpId | 同意授权的企业ID |
| InfoType | agree_external_userid_migration |
| ServiceCorpId | 服务商企业ID |
| TimeStamp | 时间戳 |
请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_new_external_userid?access_token=ACCESS_TOKEN
请求参数：
{
"external_userid_list":["xxxxx","yyyyyy"]
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| access_token | 是 | 调用接口凭证。服务商可通过“获取企业access_token”获得此调用凭证 |
| external_userid_list | 是 | 旧外部联系人id列表，建议200个，最多不超过1000个 |
权限说明：
该企业授权了该服务商第三方应用
客户联系和家校场景中，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，则原样返回。
参数说明：
| 参数 | 说明 |
|---|---|
| errcode | 返回码 |
| errmsg | 对返回码的文本描述内容 |
| new_external_userid | 新外部联系人id |
转换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"]
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| access_token | 是 | 调用接口凭证。服务商可通过“获取企业access_token”获得此调用凭证 |
| chat_id | 是 | 客户群ID |
| external_userid_list | 是 | 旧外部联系人id列表，最多不超过1000个 |
权限说明：
该企业授权了该服务商第三方应用
客户群的群主需要在应用可见范围内
返回结果：
｛
"errcode":0,
"errmsg":"ok",
"items":[
{
"external_userid":"xxxxx",
"new_external_userid":"AAAA"
},
{
"external_userid":"yyyyy",
"new_external_userid":"BBBB"
}
]
｝如果传入了新的external_userid，则原样返回。
参数说明：
| 参数 | 说明 |
|---|---|
| errcode | 返回码 |
| errmsg | 对返回码的文本描述内容 |
| new_external_userid | 新外部联系人id |
企业授权确认之后，且服务商完成了新旧external_userid的迁移，即可主动将该企业设置为“迁移完成”，设置之后，从该企业获取到的将是新的external_userid。注意，该接口需要使用provider_access_token来调用，对于有多个应用的服务商，可逐个应用进行external_userid的转换，最后再使用provider_access_token调用该接口完成设置。
当该企业同时是服务商， 并对自己授权的情况，无需调用本接口。自授权应用不在此次回收范围之内。
请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/service/externalcontact/finish_external_userid_migration?provider_access_token=ACCESS_TOKEN
请求参数：
{
"corpid":"xxxxx"
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| provider_access_token | 是 | 应用提供商的provider_access_token，获取方法参见服务商的凭证 |
| corpid | 是 | 企业corpid |
权限说明：
该企业授权了该服务商第三方应用
返回结果：
｛
"errcode":0,
"errmsg":"ok"
｝参数说明：
| 参数 | 说明 |
|---|---|
| errcode | 返回码 |
| errmsg | 对返回码的文本描述内容 |
为了更好的保护微信用户的隐私，企业微信接口将不再返回企业客户的微信unionid。服务商需要在企业客户在微信中使用服务时，根据从微信开放平台获取的unionid与openid，调用企业微信提供的转换接口，查询出对应的微信用户external_userid。
从2021年11月17号开始新授权的企业，以下接口将不再返回unionid。从2022年3月1号0点开始逐步升级历史授权的企业，升级后的企业将不再返回unionid。如果为历史授权企业调用接口设置迁移完成，该企业也将不再返回unionid。
当微信用户在微信中使用第三方应用的小程序或公众号时，第三方可将获取到的unionid与openid，调用此接口转换为企业客户或学生家长的external_userid。该接口调用频次有限，每个服务商每小时仅可调用5万次，每天仅可调用24万次，应由用户的主动行为来触发查询（例如用户进入小程序时触发），严禁批量进行ID转换，如有发现违规行为，将封禁服务商的接口调用权限。同时建议服务商的小程序路径或公众号页面链接带上corpid参数，如此可明确地转换出该企业对应的external_userid，以获得更好的性能。
请求方式：POST（HTTPS）
请求地址：https://qyapi.weixin.qq.com/cgi-bin/service/externalcontact/unionid_to_external_userid_3rd?suite_access_token=ACCESS_TOKEN
请求参数：
{
"unionid":"xxxxx",
"openid":"xxxxx",
"corpid":"xxxxx"
}参数说明：
| 参数 | 必须 | 说明 |
|---|---|---|
| suite_access_token | 是 | 第三方应用access_token |
| unionid | 是 | 微信用户的unionid |
| openid | 是 | 微信用户的openid |
| corpid | 否 | 需要换取的企业corpid，不填则拉取所有企业。建议尽可能传入corpid参数，可获得更好的性能 |
权限说明：
1. 该企业授权了该服务商第三方应用
2. 调用频率最大为5万次/小时，24万次/天
3. unionid和openid的主体需与服务商的主体一致
4. openid与unionid必须是在同一个小程序或同一个公众号获取到的
5. 相应外部成员跟进人在应用可见范围内 或 相应外部成员所属外联群群主在应用可见范围内。
6. 当微信用户为家长时，仅返回应用的可见范围内的家长。
7. 外联群场景中，本接口corpid为必填项。
8. 微信客服场景中，仅返回48小时内客服会话的external_userid。
返回结果：
｛
"errcode":0,
"errmsg":"ok",
"external_userid_info":[
{
"corpid":"AAAAA",
"external_userid":"BBBB"
},
{
"corpid":"CCCCC",
"external_userid":"DDDDD"
}
]
｝参数说明：
| 参数 | 说明 |
|---|---|
| errcode | 返回码 |
| errmsg | 对返回码的文本描述内容 |
| external_userid_info | 该unionid对应的外部联系人信息 |
| external_userid_info.corpid | 所属企业id |
| external_userid_info.external_userid | 外部联系人id |
基础连接微信办公基础连接微信办公基础连接微信办公