> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 获取 Woovi 活体检测 URL

> 获取或重新生成 Woovi 活体检测 URL，个人商户需完成该检测才能激活 BRL Pix - Woovi 账户。

使用此接口为通过 Woovi 服务商激活 BRL Pix 账户的个人商户获取 Woovi 活体检测 URL。在你使用 `trench: "Pix - Woovi"` 调用[激活个人商户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-individual.md)之前，商户必须在返回的 URL 上完成活体检测。如果商户尚未完成检测且之前的 URL 已过期，再次调用此接口会返回新的 URL。

> [!NOTE]
>
> 所有请求都必须携带 `X-BH-TOKEN` 请求头和 `Content-Type: application/json`。此接口仅适用于 KYC 验证已通过（商户状态为 `2`）且账户可使用 Pix - Woovi 通道的个人商户。请在激活请求**之前**调用：在完成活体检测之前，激活会以错误码 `-5059` 失败。

## 接口地址

`POST https://api.velafi.com/v2/merchant/woovi/liveness`

## 请求参数

**merchantId** `number` *required*

需要进行活体检测的商户 ID。

**generateNewLiveness** `boolean`

当前会被忽略：API 不会转发该值，因此始终按 `false` 处理。如需在之前的 URL 过期后获取新 URL，请再次调用此接口。

## 响应字段

**code** `number`

HTTP 风格的响应码。`200` 表示成功。

**msg** `string`

可读的状态信息，例如 `SUCCESS`。

**data** `object`

**data 字段**

**livenessId** `string`

本次活体检测会话的唯一标识符。

**livenessUrl** `string`

商户完成活体检测需访问的 URL。包含一个短期有效的 JWT。

**expiresAt** `string`

活体检测 URL 过期时间的 Unix 时间戳（秒）。

**status** `string`

当前活体检测状态：

* `PENDING` — 活体检测尚未完成；请引导商户访问 `livenessUrl`
* `COMPLETED` — 活体检测已通过；如果你尚未激活该通道，现在可以调用激活接口
* `KYC_APPROVED` — 该商户的 Pix - Woovi 通道已激活

**failReason** `string`

活体检测失败的原因（如适用）。

## 示例

```bash cURL theme={null}
curl -X POST https://api.velafi.com/v2/merchant/woovi/liveness \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 151209,
    "generateNewLiveness": false
  }'
```

```json Response theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "livenessId": "00000000-0000-0000-0000-000000000007",
    "livenessUrl": "https://app.sandbox.avenia.io/liveness/00000000-0000-0000-0000-000000000000?jwt=...",
    "expiresAt": "1788244424",
    "status": "PENDING",
    "failReason": ""
  }
}
```

> [!WARNING]
>
> `livenessUrl` 包含一个短期有效的 JWT，并在 `expiresAt` 所示的时间过期。如果 URL 在商户完成检测之前过期，请再次调用此接口以获取新的 URL。


## Related topics

- [激活商户账户](https://docs.velafi.com/cn/docs/guides/activating-merchant-account.md)
- [激活个人商户账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-individual.md)
- [更新日志](https://docs.velafi.com/cn/docs/changelog.md)
- [激活企业商户账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-business.md)
- [基础 URL](https://docs.velafi.com/cn/api-reference/basic-configuration/api-endpoint.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.