# 设置小程序名称

[调试诊断](https://developers.weixin.qq.com/console/devtools/debug?utm_source=api_tools)

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

接口英文名：setNickName

- 调用本接口可以设置小程序名称，当名称没有命中关键词，则直接设置成功；当名称命中关键词，需提交证明材料，并需要审核。审核结果会向消息与事件接收 URL 进行[事件推送](api_setnickname#名称审核结果事件推送说明)。
- 使用过程中如遇到问题，可在[开放平台服务商专区](https://developers.weixin.qq.com/community/minihome/mixflow/1355698687267438595)发帖交流

## 1. 调用方式

### HTTPS 调用

```bash
POST https://api.weixin.qq.com/wxa/setnickname?access_token=ACCESS_TOKEN
```

### 云调用

- 本接口不支持云调用。

### 第三方调用

- 本接口支持第三方平台代商家调用。

- 该接口所属的权限集 id 为：30

- 服务商获得其中之一权限集授权后，可通过使用 [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",
    "必填": "是",
    "说明": "接口调用凭证，可使用 [authorizer_access_token](/doc/oplatform/openApi/ticket-token/api_getauthorizeraccesstoken)"
  }
]
```

### 请求体 `Request Payload`

```json
[
  {
    "参数名": "nick_name",
    "类型": "string",
    "必填": "是",
    "说明": "昵称，不支持包含“小程序”关键字的昵称"
  },
  {
    "参数名": "id_card",
    "类型": "string",
    "必填": "是",
    "说明": "身份证照片 mediaid，个人号必填"
  },
  {
    "参数名": "license",
    "类型": "string",
    "必填": "是",
    "说明": "组织机构代码证或营业执照 mediaid，组织号必填"
  },
  {
    "参数名": "naming_other_stuff_1",
    "类型": "string",
    "必填": "否",
    "说明": "其他证明材料 mediaid"
  },
  {
    "参数名": "naming_other_stuff_2",
    "类型": "string",
    "必填": "否",
    "说明": "其他证明材料 mediaid"
  },
  {
    "参数名": "naming_other_stuff_3",
    "类型": "string",
    "必填": "否",
    "说明": "其他证明材料 mediaid"
  },
  {
    "参数名": "naming_other_stuff_4",
    "类型": "string",
    "必填": "否",
    "说明": "其他证明材料 mediaid"
  },
  {
    "参数名": "naming_other_stuff_5",
    "类型": "string",
    "必填": "否",
    "说明": "其他证明材料 mediaid"
  }
]
```

## 3. 返回参数

### 返回体 `Response Payload`

```json
[
  {
    "参数名": "errcode",
    "类型": "number",
    "说明": "返回码"
  },
  {
    "参数名": "errmsg",
    "类型": "string",
    "说明": "错误信息"
  },
  {
    "参数名": "wording",
    "类型": "string",
    "说明": "材料说明"
  },
  {
    "参数名": "audit_id",
    "类型": "number",
    "说明": "审核单 id，通过用于[查询改名审核状态](api_getnicknamestatus)"
  }
]
```

## 4. 注意事项

- 改名次数将在自然年 1 月 1 日和微信认证审核通过后重置为 2 次。改名次数用尽后，可通过发起微信认证实现改名。

###   其他说明

- 临时素材 mediaid 通过调用“临时素材管理接口”获取
- 请注意调用如下接口时需要使用[第三方平台接口调用令牌authorizer_access_token](/doc/oplatform/openApi/ticket-token/api_getauthorizeraccesstoken)
- [新增临时素材](/miniprogram/dev/server/API/kf-mgnt/kf-message/api_uploadtempmedia.md)
- [获取临时素材](/miniprogram/dev/server/API/kf-mgnt/kf-message/api_getmedia.md)

### 名称审核结果事件推送

[小程序改名](api_setnickname)的审核结果会向消息与事件接收 URL 推送相关通知。

### 名称审核结果事件推送说明

| 参数 | 类型 | 字段描述 |
| - | - | - |
| nickname | string | 需要更改的昵称 |
| ret | number | 审核结果 2：失败，3：成功 |
| reason | string | 审核失败的驳回原因 |

#### 推送内容解密后的示例：

```xml
<xml>
	<ToUserName><![CDATA[gh_fxxxxxxxa4b2]]></ToUserName>
	<FromUserName><![CDATA[odxxxxM-xxxxxxxx-trm4a7apsU8]]></FromUserName>
	<CreateTime>1488800000</CreateTime>
	<MsgType><![CDATA[event]]></MsgType>
	<Event><![CDATA[wxa_nickname_audit]]></Event>
	<ret>2</ret>
	<nickname>昵称</nickname>
	<reason>驳回原因</reason>
</xml>
```

## 5. 代码示例

请求示例

```json
{
  "nick_name": "XXX公司",
  "id_card": "3LaLzqiTrQcD20DlX_o-OV1",
  "license": "3LaLzqiTrQcD20DlX_o-OV22231",
  "naming_other_stuff_1": "3LaLzqiTrQcD20DlX_o-OV1-
nlYMu7sdVAL7SV2PrxVyjZFZZmB3O6LPGaYXlZWq",
  "naming_other_stuff_2": "",
}
```

返回示例

```json
{
  "errcode": 0,
  "errmsg": "ok",
  "wording": "",
  "audit_id": 12345
}
```
**注意： 若接口未返回 audit_id，说明名称已直接设置成功，无需审核；**

## 6. 错误码

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

```json
[
  {
    "错误码": "40007",
    "错误描述": "invalid media_id",
    "解决方案": "不合法的媒体文件 id"
  },
  {
    "错误码": "91001",
    "错误描述": "not fast register",
    "解决方案": "通过api注册的小程序才可调用该接口改名"
  },
  {
    "错误码": "91003",
    "错误描述": "invalid change stat",
    "解决方案": "改名状态不合法"
  },
  {
    "错误码": "91004",
    "错误描述": "invalid nickname",
    "解决方案": "昵称不合法"
  },
  {
    "错误码": "91005",
    "错误描述": "",
    "解决方案": "昵称 15 天主体保护"
  },
  {
    "错误码": "91007",
    "错误描述": "nickname used",
    "解决方案": "昵称已被占用"
  },
  {
    "错误码": "91008",
    "错误描述": "",
    "解决方案": "昵称命中 7 天侵权保护期"
  },
  {
    "错误码": "91009",
    "错误描述": "nickname need proof",
    "解决方案": "需要提交材料"
  },
  {
    "错误码": "91010",
    "错误描述": "",
    "解决方案": "其他错误"
  },
  {
    "错误码": "91011",
    "错误描述": "查不到昵称修改审核单信息",
    "解决方案": "查不到昵称修改审核单信息"
  },
  {
    "错误码": "91012",
    "错误描述": "",
    "解决方案": "其他错误"
  },
  {
    "错误码": "91013",
    "错误描述": "",
    "解决方案": "占用名字过多"
  },
  {
    "错误码": "91014",
    "错误描述": "diff master plus",
    "解决方案": "+号规则 同一类型关联名主体不一致"
  },
  {
    "错误码": "91015",
    "错误描述": "diff master",
    "解决方案": "原始名不同类型主体不一致"
  },
  {
    "错误码": "91016",
    "错误描述": "name more owner",
    "解决方案": "名称占用者 ≥2"
  },
  {
    "错误码": "91017",
    "错误描述": "other diff master plus",
    "解决方案": "+号规则 不同类型关联名主体不一致"
  },
  {
    "错误码": "91019",
    "错误描述": "小程序正在审核中",
    "解决方案": "小程序正在审核中"
  },
  {
    "错误码": "91028",
    "错误描述": "试用小程序不支持使用该接口更改名称",
    "解决方案": ""
  },
  {
    "错误码": "91029",
    "错误描述": "no rename quota",
    "解决方案": "可通过认证改名"
  }
]
```

## 7. 适用范围

本接口支持「第三方平台」账号类型代调用，权限集请参考「调用方式」部分。其他账号类型如无特殊说明，均不可调用。