Saltar al contenido principal

Verificación de Edad

Para el flujo de integración completo, consulta 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​

Headers
HeaderValor
AuthorizationBearer <access_token> (consulta Autenticación)
APIKEYClave de API aprovisionada — debe tener habilitadas las capacidades de Verificación de Edad.
Content-Typeapplication/json
Parámetros del cuerpo
CampoTipoRequeridoDescripción
subjectobjetosí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 (consulta 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 (ej.: 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 × 480 (estándar HD)
  • Tamaño máximo de archivo: 800 KB (se recomienda compresión JPEG92)
  • Los tokens JWT del SDK vencen 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 tu 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. Úsalo con Obtener proceso para nuevas consultas.
statusentero3 (finalizado con éxito), 5 (error). Usa solo status = 3 para decisiones de negocio. Para todos los valores posibles, consulta 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.
livenessentero1 (aprobado), 2 (fallido) — presente solo cuando la Detección de Vida está habilitada.
400 Bad Request

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

403 Forbidden

Token Bearer o APIKEY ausente, vencido o inválido. Consulta Autenticación.

409 Conflict

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

429 Too Many Requests

Límite de tasa alcanzado. Reintenta después del intervalo indicado en el header de respuesta Retry-After. Consulta 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 con la imagen o inyección.
20807A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.Resolución de imagen 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 se incluye Detección de Vida o Verificación de Identidad en el flujo — no requerido para flujos de solo Verificación de Edad.
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.El payload supera 800 KB; comprime 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.El formato de subject.phone es 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.Parámetro de imagen selfie ausente.
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.Parámetro subject.code ausente. Solo se activa cuando se incluye Detección de Vida o Verificación de Identidad en el flujo — no requerido para flujos de solo Verificación de Edad.
20004O parâmetro subject não foi informado.Objeto subject ausente.
20003The request body is missing or invalid.Payload nulo o malformado.
20002O parâmetro APIKey não foi informado.Header APIKEY ausente.
20001O parâmetro authtoken não foi informado.Header de token de autenticación ausente.
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 supera la ventana de validez de 10 minutos.
10506The imageBase64 field is not a valid JWT from SDK.El campo imageBase64 no es un JWT válido generado por el SDK.

Próximos pasos​

Última actualización el