# 转换openid

> 接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考[接口调用指南](/doc/oplatform/developers/dev/guide.md)。

接口英文名：changeopenid

该接口用于公众号、服务号之后进行 openid 转换。

##### 应用场景

公众号/服务号账号迁移后，关注用户的 openid 会变化，微信用户关注不同的公众号或服务号，对应的openid是不一样的，迁移成功后，关注用户的openid 以目标账号（即新账号）对应的 openid 为准。原账号非个人主体的，可以通过当前接口转换openid。

##### 接口用途
当账号迁移后，可以通过该接口：

1. 将原账号关注用户的openid转换为新账号的openid。
2. 将有授权关系用户的openid转换为新账号的openid。
3. 将卡券关联用户的openid转换为新账号的openid。

##### 名词解释

- 原账号：准备要迁移的账号，当审核完成且管理员确认后即被回收。
-  新账号：用来接纳关注用户的账号。新账号在整个流程中均能正常使用。

##### 注意

1. 原账号为个人主体的，不支持使用该接口进行。
2. 一定要在原账号被冻结之前，最好是准备提交审核前，获取原账号的用户列表。如果没有原账号的用户列表，用不了转换工具。如果原账号被回收，这时候也没办法调用接口获取用户列表。
3. 转换openid的API接口如下，可在账号迁移审核完成后开始调用，并最多保留15天。若账号迁移没完成，调用时无返回结果或报错。账号迁移15天后，该转换接口将会失效、无法拉取到数据。

## 1. 调用方式

### HTTPS 调用

```bash
POST https://api.weixin.qq.com/cgi-bin/changeopenid?access_token=ACCESS_TOKEN
```

### 云调用

- 本接口不支持云调用。

### 第三方调用

- 本接口支持第三方平台使用 [component_access_token](/doc/oplatform/developers/dev/ComponentAccessToken.md) 自己调用，同时还支持代商家调用。

- 服务商获得任意权限集授权后，即可通过使用 [authorizer_access_token](/doc/oplatform/developers/dev/AuthorizerAccessToken.md) 代商家进行调用，具体可查看 [第三方调用](/doc/oplatform/Third-party_Platforms/2.0/Before_Develop/call_interface.md) 说明文档。

## 2. 请求参数

### 查询参数 `Query String Parameters`

```json
[
  {
    "参数名": "access_token",
    "类型": "string",
    "必填": "是",
    "示例": "ACCESS_TOKEN",
    "说明": "接口调用凭证，可使用 [access_token](/doc/subscription/api/base/api_getaccesstoken)"
  }
]
```

### 请求体 `Request Payload`

```json
[
  {
    "参数名": "from_appid",
    "类型": "string",
    "必填": "是",
    "示例": "gh_91ae50dfeb1c",
    "说明": "原账号的原始id，不是appid"
  },
  {
    "参数名": "openid_list",
    "类型": "array",
    "必填": "是",
    "示例": "",
    "说明": "第1步中拉取的原账号用户列表，这些必须是旧账号目前关注的才行，否则会出错；一次最多100个。"
  }
]
```

## 3. 返回参数

### 返回体 `Response Payload`

```json
[
  {
    "参数名": "errcode",
    "类型": "number",
    "说明": "错误码"
  },
  {
    "参数名": "errmsg",
    "类型": "string",
    "说明": "错误描述"
  },
  {
    "参数名": "result_list",
    "类型": "objarray",
    "说明": "openid结果列表"
  }
]
```

">

### Res.result_list(Array) `Object Payload`

openid结果列表

```json
[
  {
    "参数名": "ori_openid",
    "类型": "string",
    "示例": "oEmYbwN-n24jxvk4Sox81qedINkQ",
    "说明": "旧openid"
  },
  {
    "参数名": "new_openid",
    "类型": "string",
    "示例": "o2FwqwI9xCsVadFah_HtpPfaR-X4",
    "说明": "新openid"
  },
  {
    "参数名": "err_msg",
    "类型": "string",
    "示例": "ok",
    "说明": "错误描述。\"ori_openid error\"则表示这个openid目前没有关注旧账号。"
  }
]
```

## 4. 注意事项

本接口无特殊注意事项

## 5. 代码示例

请求示例

```json
{
    "from_appid": "gh_91ae50dfeb1c",
    "openid_list": "[\"oEmYbwN-n24jxvk4Sox81qedINkQ\",\"oEmYbwH9uVd4RKJk7ZZg6S zL6tTo\"]"
}
```

返回示例

```json
{
    "errcode": 0,
    "errmsg": "",
    "result_list": [
        {
            "ori_openid": "oEmYbwN-n24jxvk4Sox81qedINkQ",
            "new_openid": "o2FwqwI9xCsVadFah_HtpPfaR-X4",
            "err_msg": "ok"
        }
    ]
}
```

## 6. 错误码

以下是本接口的错误码列表，其他错误码可参考 [通用错误码](/doc/oplatform/developers/errCode/README.md)；调用接口遇到报错，可使用官方提供的 [API 诊断工具](https://developers.weixin.qq.com/console/devtools/debug?utm_source=api_errcode) 辅助定位和分析问题。

```json
[
  {
    "错误码": "63178",
    "错误描述": "appid wrong",
    "解决方案": "from_appid参数错误，和调用的账号并没有迁移关系"
  },
  {
    "错误码": "63182",
    "错误描述": "openid_list empty",
    "解决方案": "openid是空"
  },
  {
    "错误码": "63183",
    "错误描述": "appid error",
    "解决方案": "appid没有迁移关系"
  }
]
```

## 7. 适用范围

该接口用于公众号、服务号之后进行 openid 转换，并且在账号迁移审核完成后开始调用，并最多保留15天。若账号迁移没完成，调用时无返回结果或报错。账号迁移15天后，该转换接口将会失效、无法拉取到数据。