年龄验证

完整集成流程请参阅 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

已达到速率限制。请在 Retry-After 响应头指示的时间间隔后重试。参见速率限制。

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 格式无效（国际区号 + 区号 + 号码，共 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.	access-token 包含无效字符。
10502	O token informado está expirado.	access-token 已过期。
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.	服务器端处理错误。

下一步

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