Verificación de Edad

Para el flujo de integración completo, consulte Descripción general de la API.

Endpoint

Entorno	URL
Producción	POST https://api.id.unico.app/processes/v1
Sandbox	POST https://api.id.uat.unico.app/processes/v1

Solicitud

Encabezados

Encabezado	Valor
Authorization	Bearer <access_token> (consulte Autenticación)
APIKEY	Clave API provisionada: debe tener las capacidades de Verificación de Edad habilitadas.
Content-Type	application/json

Parámetros del cuerpo

Campo	Tipo	Requerido	Descripción
subject	object	sí	Contenedor de información del usuario.
subject.code	string	condicional	CPF (BR) o CURP (MX), sin formato. Requerido cuando el flujo incluye Detección de Vida o Verificación de Identidad (consulte la capacidad de Verificación de Edad); no requerido para flujos de solo Verificación de Edad.
subject.name	string	no	Nombre completo del usuario.
subject.gender	string	no	M para masculino o F para femenino.
subject.birthDate	string (ISO 8601)	no	Fecha de nacimiento (YYYY-MM-DD).
subject.email	string	no	Dirección de correo electrónico del usuario.
subject.phone	string	no	Número de teléfono: código de país + código de área + número, sin separadores (por ejemplo, 5519725570707).
useCase	string	no	Identificador del caso de uso de la operación.
subsidiaryId	string	no	ID de sucursal: requerido solo si existen múltiples sucursales.
imageBase64	string	sí	Salida cifrada del SDK o imagen en base64 (PNG, JPEG, WebP).

Requisitos de imagen

• Resolución mínima: 640 x 480 (estándar HD)
• Tamaño máximo de archivo: 800 KB (se recomienda compresión JPEG92)
• Los tokens JWT del SDK expiran después de 10 minutos y solo pueden usarse una vez

Ejemplo

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();

Respuestas

200 OK

Los campos de respuesta devueltos dependen de las capacidades habilitadas para su APIKEY.

Solo Verificación de Edad (sin Detección de Vida, sin Verificación de Identidad):

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idAge": { "result": "yes" }
}

Verificación de Edad + Detección de Vida + Verificación de Identidad:

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "idAge": { "result": "yes" },
  "liveness": 1
}

Campo	Tipo	Descripción
id	string (UUID)	Identificador del proceso. Use con Obtener proceso para re-consultas.
status	integer	3 (finalizado con éxito), 5 (error). Solo use status = 3 para decisiones de negocio. Para todos los valores posibles, consulte Obtener proceso.
idAge.result	string	yes, no, inconclusive - Resultado de Verificación de Edad. Presente en todas las respuestas.
unicoId.result	string	yes, no, inconclusive - presente solo cuando la Verificación de Identidad está habilitada.
liveness	integer	1 (aprobado), 2 (fallido) - presente solo cuando la Detección de Vida está habilitada.

400 Bad Request

El payload está malformado, la imagen es inválida o faltan campos requeridos.

403 Forbidden

Token Bearer o APIKEY ausente, expirado o inválido. Consulte Autenticación.

409 Conflict

El processId proporcionado ya existe para este tenant. Consulte Códigos de error a continuación.

429 Too Many Requests

Límite de tasa alcanzado. Cuando su sistema recibe un error HTTP 429, debe implementar mecanismos para prevenir fallos en cascada y evitar empeorar la restricción.

Mejores prácticas:

• Período de espera (backoff): Detenga o limite inmediatamente las solicitudes subsecuentes de su sistema. No reintente continuamente solicitudes fallidas en un bucle cerrado.
• Cola y limitación: Almacene en buffer o encole las solicitudes salientes de su lado para controlar el flujo de tráfico antes de reenviarlas.
• Backoff exponencial con jitter: Al reintentar, aumente el tiempo de espera exponencialmente entre intentos (por ejemplo, 1 s, 2 s, 4 s, 8 s) y agregue un pequeño retraso aleatorio ("jitter") para prevenir un efecto manada donde todas las solicitudes en cola reintentan en el mismo milisegundo.

advertencia

Golpear continuamente un endpoint con límite de tasa sin aplicar backoff puede prolongar el período de restricción e impactar severamente el rendimiento operativo de su sistema. Limitar adecuadamente las solicitudes de su lado asegura una integración más fluida y resiliente.

Para límites predeterminados, solicitudes de aumento y detalles adicionales, consulte Límites de tasa.

500 Internal Server Error

Error inesperado del servidor.

Códigos de error

400 Bad Request

Código	Mensaje	Descripción
20900	O base64 informado não é válido.	Parámetro base64 inválido; posible problema de imagen o inyección.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	La resolución de la imagen está por debajo del umbral mínimo.
20509	The subject.name field is invalid.	subject.name contiene caracteres inválidos.
20508	The subject.gender field is invalid.	subject.gender debe ser M o F.
20507	O parâmetro subject.code é inválido.	Valor de identificador malformado o inexistente. Solo se activa cuando la Detección de Vida o la Verificación de Identidad está incluida en el flujo, no se requiere para flujos de solo Verificación de Edad.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	El payload excede 800 KB; comprima a JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Formato no compatible o prefijo base64 inválido.
20062	The useCase field is invalid.	Valor no reconocido en el campo useCase.
20021	The subject.phone field is invalid.	Formato de subject.phone inválido (IDD + código de área + número, 13 caracteres).
20019	The subject.birthDate field is invalid.	subject.birthDate está fuera del formato ISO 8601 (YYYY-MM-DD).
20009	O parâmetro imagebase64 não foi informado.	Falta el parámetro de imagen selfie.
20008	The subject.email field is invalid.	Formato de correo electrónico inválido en subject.email.
20005	O parâmetro subject.code não foi informado.	Falta el parámetro subject.code. Solo se activa cuando la Detección de Vida o la Verificación de Identidad está incluida en el flujo, no se requiere para flujos de solo Verificación de Edad.
20004	O parâmetro subject não foi informado.	Falta el objeto subject.
20003	The request body is missing or invalid.	Payload nulo o malformado.
20002	O parâmetro APIKey não foi informado.	Falta el encabezado APIKEY.
20001	O parâmetro authtoken não foi informado.	Falta el encabezado del token de autenticación.
10508	The JWT with the captured face has already been used.	El JWT solo puede consumirse una vez.
10507	The JWT with the captured face is expired.	El JWT excede la ventana de validez de 10 minutos.
10506	The imageBase64 field is not a valid JWT from SDK.	El imageBase64 no es un JWT válido generado por el SDK.

403 Forbidden

Código	Mensaje	Descripción
30017	User does not have permission to perform this action.	JWT malformado o usuario sin permiso para realizar esta operación.
30017	Jwt header is an invalid JSON.	El token de acceso contiene caracteres inválidos.
10502	O token informado está expirado.	Token de acceso expirado.
10501	O token informado é inválido.	Token de autenticación inválido.
10201	O AppKey informado é inválido.	APIKEY ausente o inexistente.

409 Conflict

Código	Mensaje	Descripción
20073	The processID already exists.	El processId proporcionado ya existe para este tenant.

500 Internal Server Error

Código	Mensaje	Descripción
99999	Internal failure! Try again later.	Error de procesamiento del lado del servidor.

Qué sigue

• Para consultar un proceso existente, consulte Obtener proceso.