Saltar al contenido principal

Verificación de Edad

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

Endpoint​

EntornoURL
ProducciónPOST https://api.id.unico.app/processes/v1
SandboxPOST https://api.id.uat.unico.app/processes/v1

Solicitud​

Encabezados
EncabezadoValor
AuthorizationBearer <access_token> (consulte Autenticación)
APIKEYClave API provisionada: debe tener las capacidades de Verificación de Edad habilitadas.
Content-Typeapplication/json
Parámetros del cuerpo
CampoTipoRequeridoDescripción
subjectobjectsíContenedor de información del usuario.
subject.codestringcondicionalCPF (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.namestringnoNombre completo del usuario.
subject.genderstringnoM para masculino o F para femenino.
subject.birthDatestring (ISO 8601)noFecha de nacimiento (YYYY-MM-DD).
subject.emailstringnoDirección de correo electrónico del usuario.
subject.phonestringnoNúmero de teléfono: código de país + código de área + número, sin separadores (por ejemplo, 5519725570707).
useCasestringnoIdentificador del caso de uso de la operación.
subsidiaryIdstringnoID de sucursal: requerido solo si existen múltiples sucursales.
imageBase64stringsí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 -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..."
  }'

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
}
CampoTipoDescripción
idstring (UUID)Identificador del proceso. Use con Obtener proceso para re-consultas.
statusinteger3 (finalizado con éxito), 5 (error). Solo use status = 3 para decisiones de negocio. Para todos los valores posibles, consulte Obtener proceso.
idAge.resultstringyes, no, inconclusive - Resultado de Verificación de Edad. Presente en todas las respuestas.
unicoId.resultstringyes, no, inconclusive - presente solo cuando la Verificación de Identidad está habilitada.
livenessinteger1 (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​

CódigoMensajeDescripción
20900O base64 informado não é válido.Parámetro base64 inválido; posible problema de imagen o inyección.
20807A 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.
20509The subject.name field is invalid.subject.name contiene caracteres inválidos.
20508The subject.gender field is invalid.subject.gender debe ser M o F.
20507O 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.
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.El payload excede 800 KB; comprima a JPEG92.
20505O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.Formato no compatible o prefijo base64 inválido.
20062The useCase field is invalid.Valor no reconocido en el campo useCase.
20021The subject.phone field is invalid.Formato de subject.phone inválido (IDD + código de área + número, 13 caracteres).
20019The subject.birthDate field is invalid.subject.birthDate está fuera del formato ISO 8601 (YYYY-MM-DD).
20009O parâmetro imagebase64 não foi informado.Falta el parámetro de imagen selfie.
20008The subject.email field is invalid.Formato de correo electrónico inválido en subject.email.
20005O 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.
20004O parâmetro subject não foi informado.Falta el objeto subject.
20003The request body is missing or invalid.Payload nulo o malformado.
20002O parâmetro APIKey não foi informado.Falta el encabezado APIKEY.
20001O parâmetro authtoken não foi informado.Falta el encabezado del token de autenticación.
10508The JWT with the captured face has already been used.El JWT solo puede consumirse una vez.
10507The JWT with the captured face is expired.El JWT excede la ventana de validez de 10 minutos.
10506The imageBase64 field is not a valid JWT from SDK.El imageBase64 no es un JWT válido generado por el SDK.

Qué sigue​

Última actualización el