年龄验证

有关完整的集成流程，请参阅 API 概述。

端点

环境	URL
生产环境	POST https://api.id.unico.app/processes/v1
沙箱环境	POST https://api.id.uat.unico.app/processes/v1

请求

请求头

请求头	值
Authorization	Bearer <access_token>（参见认证）
APIKEY	已配置的 API 密钥 — 必须启用年龄验证功能。
Content-Type	application/json

请求体参数

字段	类型	必填	描述
subject	object	是	用户信息容器。
subject.code	string	有条件	CPF（BR）或 CURP（MX），不含格式化字符。当流程包含活体检测或身份验证时必填（参见年龄验证功能）；仅年龄验证流程不需要。
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 分钟后过期，且只能使用一次

示例

cURL

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": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "AgeVerification",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Node.js

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: '[email protected]',
      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)	流程标识符。使用获取流程进行重新查询。
status	integer	3（成功完成）、5（错误）。仅使用 status = 3 做业务决策。有关所有可能的值，请参阅获取流程。
idAge.result	string	yes、no、inconclusive — 年龄验证结果。所有响应中均存在。
unicoId.result	string	yes、no、inconclusive — 仅在启用身份验证时出现。
liveness	integer	1（通过）、2（未通过） — 仅在启用活体检测时出现。

400 Bad Request

请求体格式错误、图像无效或缺少必填字段。

403 Forbidden

Bearer 令牌或 APIKEY 缺失、过期或无效。请参阅认证。

409 Conflict

提供的 processId 已存在于此租户中。请参阅下方错误代码。

429 Too Many Requests

已达到速率限制。当您的系统收到 HTTP 429 错误时，您必须实施机制以防止级联故障并避免加重限制。

最佳实践：

• 冷却期（退避）： 立即停止或限制系统中的后续请求。不要在紧密循环中持续重试失败的请求。
• 队列和限流： 在您端缓冲或排队传出请求，以在重新发送之前控制流量。
• 指数退避与抖动： 重试时，以指数方式增加尝试之间的等待时间（例如 1 秒、2 秒、4 秒、8 秒），并添加小的随机延迟（"抖动"）以防止所有排队请求在完全相同的毫秒重试的"群体效应"。

警告

在未退避的情况下持续请求被限速的端点会延长限制期并严重影响系统的运行吞吐量。在您端正确限制请求可确保更平稳、更具弹性的集成。

有关默认限制、增加请求和其他详细信息，请参阅速率限制。

500 Internal Server Error

意外的服务器错误。

错误代码

400 Bad Request

代码	消息	描述
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。

403 Forbidden

代码	消息	描述
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 缺失或不存在。

409 Conflict

代码	消息	描述
20073	The processID already exists.	提供的 processId 已存在于此租户中。

500 Internal Server Error

代码	消息	描述
99999	Internal failure! Try again later.	服务端处理错误。

下一步

• 有关查询现有流程，请参阅获取流程。