---
title: 年龄验证
description: 创建年龄验证流程。可选择在单个请求中结合活体检测和身份验证。
canonical: https://developer.unico.io/zh-CN/dual-api/developers/api-reference/api/post-processes-age-validation
locale: zh-CN
generated_by: markdown-export
---

- [/zh-CN/](/zh-CN/)
- [API 参考](/zh-CN/dual-api/developers/api-reference/)
- [API](/zh-CN/dual-api/developers/api-reference/api/)
- Age Verification

**本页内容# 年龄验证

有关完整的集成流程，请参阅 [API 概述](/zh-CN/dual-api/developers/api-reference/api/)。
### 端点​

环境URL**生产环境**`POST https://api.id.unico.app/processes/v1`**沙箱环境**`POST https://api.id.uat.unico.app/processes/v1`
### 请求​

请求头
请求头值`Authorization``Bearer <access_token>`（参见[认证](/zh-CN/dual-api/developers/api-reference/authentication)）`APIKEY`已配置的 API 密钥 — 必须启用年龄验证功能。`Content-Type``application/json`
请求体参数
字段类型必填描述`subject`object是用户信息容器。`subject.code`string有条件CPF（BR）或 CURP（MX），不含格式化字符。当流程包含活体检测或身份验证时必填（参见[年龄验证功能](/zh-CN/dual-api/capabilities/age-verification)）；仅年龄验证流程不需要。`subject.name`string否用户全名。`subject.gender`string否`M` 表示男性，`F` 表示女性。`subject.birthDate`string (ISO 8601)否出生日期（`YYYY-MM-DD`）。`subject.email`string否用户的电子邮件地址。`subject.phone`string否电话号码：国家代码 + 区号 + 号码，无分隔符（例如 `5519725570707`）。`useCase`string否操作的场景标识符。`subsidiaryId`string否分支 ID — 仅在存在多个分支时需要。`imageBase64`string是加密的 SDK 输出或 base64 图像（PNG、JPEG、WebP）。
图像要求
最低分辨率：640 × 480（HD 标准）
最大文件大小：800 KB（建议使用 JPEG92 压缩）
来自 SDK 的 JWT 令牌 在 **10 分钟**后过期，且只能使用**一次**

### 示例​

cURLNode.js```
curl -X POST https://api.id.unico.app/processes/v1 \  -H "Authorization: Bearer $TOKEN" \  -H "APIKEY: $API_KEY" \  -H "Content-Type: application/json" \  -d '{    "subject": {      "code": "12345678909",      "name": "Luke Skywalker",      "birthDate": "2000-05-20",      "email": "luke@example.com",      "phone": "5519725570707"    },    "useCase": "AgeVerification",    "imageBase64": "/9j/4AAQSkZJR..."  }'
```

```
import fetch from 'node-fetch';const res = await fetch('https://api.id.unico.app/processes/v1', {  method: 'POST',  headers: {    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,    'APIKEY': process.env.UNICO_API_KEY,    'Content-Type': 'application/json'  },  body: JSON.stringify({    subject: {      code: '12345678909',      name: 'Luke Skywalker',      birthDate: '2000-05-20',      email: 'luke@example.com',      phone: '5519725570707'    },    useCase: 'AgeVerification',    imageBase64: capturedImage  })});const result = await res.json();
```

### 响应​

200 OK
返回的响应字段取决于为您的 APIKEY 启用了哪些功能。
**仅年龄验证**（无活体检测，无身份验证）：
```
{  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",  "status": 3,  "idAge": { "result": "yes" }}
```

**年龄验证 + 活体检测 + 身份验证**：
```
{  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",  "status": 3,  "unicoId": { "result": "yes" },  "idAge": { "result": "yes" },  "liveness": 1}
```

字段类型描述`id`string (UUID)流程标识符。使用[获取流程](/zh-CN/dual-api/developers/api-reference/api/get-process)进行重新查询。`status`integer`3`（成功完成）、`5`（错误）。仅使用 `status = 3` 做业务决策。有关所有可能的值，请参阅[获取流程](/zh-CN/dual-api/developers/api-reference/api/get-process)。`idAge.result`string`yes`、`no`、`inconclusive` — 年龄验证结果。所有响应中均存在。`unicoId.result`string`yes`、`no`、`inconclusive` — 仅在启用身份验证时出现。`liveness`integer`1`（通过）、`2`（未通过） — 仅在启用活体检测时出现。
### 错误代码​

400 Bad Request403 Forbidden409 Conflict429 Too Many Requests500 Internal Server Error代码消息描述`20900`O base64 informado não é válido.base64 参数无效；可能存在图像或注入问题。`20807`A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.图  像分辨率低于最低阈值。`20509`The subject.name field is invalid.`subject.name` 包含无效字符。`20508`The subject.gender field is invalid.`subject.gender` 必须为 `M` 或 `F`。`20507`O parâmetro subject.code é inválido.格式错误或不存在的标识符值。仅在流程包含活体检测或身份验证时触发 — 仅年龄验证流程不需要。`20506`O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.请求体超过 800 KB；压缩为 JPEG92。`20505`O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.不支持的格式或无效的 base64 前缀。`20062`The useCase field is invalid.`useCase` 字段中有无法识别的值。`20021`The subject.phone field is invalid.`subject.phone` 格式无效（IDD + 区号 + 号码，13 个字符）。`20019`The subject.birthDate field is invalid.`subject.birthDate` 不符合 ISO 8601 格式（`YYYY-MM-DD`）。`20009`O parâmetro imagebase64 não foi informado.缺少自拍图像参数。`20008`The subject.email field is invalid.`subject.email` 中的电子邮件格式无效。`20005`O parâmetro subject.code não foi informado.缺少 `subject.code` 参数。仅在流程包含活体检测或身份验证时触发 — 仅年龄验证流程不需要。`20004`O parâmetro subject não foi informado.缺少 subject 对象。`20003`The request body is missing or invalid.空或格式错误的请求体。`20002`O parâmetro APIKey não foi informado.缺少 APIKEY 请求头。`20001`O parâmetro authtoken não foi informado.缺少认证令牌请求头。`10508`The JWT with the captured face has already been used.JWT 只能使用一次。`10507`The JWT with the captured face is expired.JWT 超过 10 分钟有效期窗口。`10506`The imageBase64 field is not a valid JWT from SDK.`imageBase64` 不是由 SDK 生成的有效 JWT。Bearer 令牌或 `APIKEY` 缺失、过期或无效。请参阅[认证](/zh-CN/dual-api/developers/api-reference/authentication)。代码消息描述`30017`User does not have permission to perform this action.JWT 格式错误或用户无权执行此操作。`30017`Jwt header is an invalid JSON.访问令牌包含无效字符。`10502`O token informado está expirado.访问令牌已过期。`10501`O token informado é inválido.认证令牌无效。`10201`O AppKey informado é inválido.APIKEY 缺失或不存在。代码消息描述`20073`The processID already exists.提供的 `processId` 已存在于此租户中。已达到速率限制。当您的系统收到 HTTP 429 错误时，您必须实施机制以防止级联故障并避免加重限制。**最佳实践：**
**冷却期（退避）：** 立即停止或限制系统中的后续请求。不要在紧密循环中持续重试失败的请求。
**队列和限流：** 在您端缓冲或排队传出请求，以在重新发送之前控制流量。
**指数退避与抖动：** 重试时，以指数方式增加尝试之间的等待时间（例如 1 秒、2 秒、4 秒、8 秒），并添加小的随机延迟（"抖动"）以防止所有排队请求在完全相同的毫秒重试的"群体效应"。
警告在未退避的情况下持续请求被限速的端点会**延长限制期**并严重影响系统的运行吞吐量。在您端正确限制请求可确保更平稳、更具弹性的集成。有关默认限制、增加请求和其他详细信息，请参阅[速率限制](/zh-CN/dual-api/developers/api-reference/rate-limits)。代码消息描述`99999`Internal failure! Try again later.服务端处理错误。
### 下一步​

有关查询现有流程，请参阅[获取流程](/zh-CN/dual-api/developers/api-reference/api/get-process)。
最后更新 于 2026年10月8日**