# 发起小程序管理员人脸核身

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

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

接口英文名：createIcpVerifyTask

发起备案小程序管理员人脸核身，调用该接口时会向小程序的管理员发送一条备案人脸核身通知，管理员点击该通知即可进行人脸核身。待管理员完成核身之后，平台会推送人脸核身完成事件到服务商服务器，服务商也可以使用查询人脸核身任务状态接口来轮询任务状态和结果。

本接口也可在一步申请小程序认证及备案时（详情请参考[服务商代认证及备案介绍](/doc/oplatform/Third-party_Platforms/2.0/product/wxverifyicp.md)），用于完成小程序管理员授权、人脸核身以及短信核验。

使用过程中如遇到问题，可在[小程序备案](https://developers.weixin.qq.com/community/minihome/mixflow/3398116438949937159)专区发帖交流

## 1. 调用方式

### HTTPS 调用

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

### 云调用

- 本接口不支持云调用。

### 第三方调用

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

- 该接口所属的权限集 id 为：18、156

- 服务商获得其中之一权限集授权后，可通过使用 [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
[
  {
    "参数名": "along_with_auth",
    "类型": "boolean",
    "必填": "否",
    "说明": "小程序认证及备案二合一场景，填 \u0000INLINECODE_2\u0000，否则为小程序备案场景。默认值为 \u0000INLINECODE_3\u0000。"
  }
]
```

## 3. 返回参数

### 返回体 `Response Payload`

```json
[
  {
    "参数名": "task_id",
    "类型": "string",
    "说明": "人脸核验任务id"
  },
  {
    "参数名": "errcode",
    "类型": "number",
    "说明": "错误码"
  },
  {
    "参数名": "errmsg",
    "类型": "string",
    "说明": "错误信息"
  },
  {
    "参数名": "verify_url",
    "类型": "string",
    "说明": "人脸核验任务url，\u0000INLINECODE_5\u0000 填 \u0000INLINECODE_6\u0000 时返回。"
  }
]
```

## 4. 注意事项

1. 人脸核身视频会用于生成核验照片，背景需白色或接近浅色，核验人不能裸露上半身，不能戴帽子、耳机、口罩等遮挡面部的物品。
2. 人脸核身通知有效期为 24 小时，如果在通知有效期内核身未能通过，可以再次点击通知进行重试，无需重新发起，过期后需重新发起。
3. 小程序认证及备案二合一场景下（`along_with_auth` 为 `true`）人脸核身任务 `task_id` 有效期为 1 天，小程序备案场景下（`along_with_auth` 为 `false`）为 3 天。为避免申请备案时 `task_id` 过期，请确保其余所有备案材料已准备好，以及备案前置条件已完成，再发起人脸核身。
4. 发起人脸核身前，请留意当天申请小程序备案接口是否还有剩余调用限额，以免需要反复发起。
5. 在小程序认证及备案二合一场景下（`along_with_auth` 为 `true`），如果流程已进行到备案阶段，则仅需要完成人脸核验，无需再进行小程序管理员授权以及短信核验。后台会自动根据小程序当前状态判断需要完成哪些步骤，调用方无需判断。

**人脸核身常见失败及解决方案**

| 失败原因             | 解决方案                                   |
| -------------------- | ------------------------------------------ |
| 人脸视频背景非纯白色 | 请尝试在无杂物的白色背景下重新进行人脸核身 |
| 人脸视频人脸占比太大 | 请尽量尝试远离镜头重新进行人脸核身         |
| 人脸视频闭眼占比过多 | 请尽量尝试睁开眼睛重新进行人脸核身         |
| 人脸视频光线过曝     | 请尝试去暗一点的地方重新进行人脸核身       |
| 人脸视频光线过暗     | 请尝试去亮一点的地方重新进行人脸核身       |

# 其他说明 

## 事件推送

小程序管理员人脸核身完成事件。当小程序管理员完成人脸核身时会推送该事件。服务商要接收事件推送，请移步：[授权事件接收配置](/doc/oplatform/Third-party_Platforms/2.0/operation/thirdparty/prepare.md#_3%E3%80%81%E6%8E%88%E6%9D%83%E4%BA%8B%E4%BB%B6%E6%8E%A5%E6%94%B6-%E9%85%8D%E7%BD%AE)

如果发起时 `along_with_auth` 填 `true`，则除了人脸核身完成时会推送事件，认证短信核验通过时还会推送事件。

#### 推送参数说明

| 参数                   | 类型   | 说明                                                           |
| ---------------------- | ------ | -------------------------------------------------------------- |
| InfoType               | string | 消息类型，固定为 `notify_icpfiling_verify_result`              |
| AppId                  | string | 服务商唯一id                                                   |
| task_id                | string | 人脸核验任务id                                                 |
| verify_appid           | string | 小程序唯一id                                                   |
| result                 | number | 人脸核验结果： 2-核验失败；3-核验成功                          |
| along_with_auth_result | number | 发起时 `along_with_auth` 填 `true` 时有效：9. 认证短信核验通过。 |

## 推送数据示例

**人脸核身完成时事件**

```xml
<xml>
    <AppId><![CDATA[wx1234567890abcdef]]></AppId>
    <CreateTime>1689839779</CreateTime>
    <InfoType><![CDATA[notify_icpfiling_verify_result]]></InfoType>
    <task_id><![CDATA[R5PqRPNb6GmG3i0rqd4pTg]]></task_id>
    <verify_appid><![CDATA[wxabcdef1234567890]]></verify_appid>
    <result>3</result>
</xml>
```

**认证短信核验通过时事件**

```xml
<xml>
    <AppId><![CDATA[wx1234567890abcdef]]></AppId>
    <CreateTime>1689839779</CreateTime>
    <InfoType><![CDATA[notify_icpfiling_verify_result]]></InfoType>
    <task_id><![CDATA[R5PqRPNb6GmG3i0rqd4pTg]]></task_id>
    <verify_appid><![CDATA[wxabcdef1234567890]]></verify_appid>
    <result>3</result>
    <along_with_auth_result>9</along_with_auth_result>
</xml>
```

## 5. 代码示例

### 5.1 小程序备案场景，仅需完成人脸核身

请求示例

```bach
curl -XPOST 'https://api.weixin.qq.com/wxa/icp/create_icp_verifytask?access_token=ACCESS_TOKEN' -d '{}'
```

返回示例

```json
{
  "errcode": 0,
  "errmsg": "",
  "task_id": "R5PqRPNb6GmG3i0rqd4pTg"
}
```

### 5.2 小程序认证及备案二合一场景，需完成小程序管理员授权、人脸核身以及短信核验

请求示例

```bach
curl -XPOST 'https://api.weixin.qq.com/wxa/icp/create_icp_verifytask?access_token=ACCESS_TOKEN' -d '{"along_with_auth": true}'
```

返回示例

```json
{
  "errcode": 0,
  "errmsg": "",
  "task_id": "R5PqRPNb6GmG3i0rqd4pTg",
  "verify_url": "https://mp.weixin.qq.com"
}
```

## 6. 错误码

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

```json
[
  {
    "错误码": "-1",
    "错误描述": "system error",
    "解决方案": "系统繁忙，此时请开发者稍候再试"
  },
  {
    "错误码": "0",
    "错误描述": "ok",
    "解决方案": "ok"
  }
]
```

## 7. 适用范围

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