API de comprobación de edad

Estime si una persona es lo bastante mayor a partir de un selfi, con un respaldo en la fecha de nacimiento del documento de identidad cuando la estimación queda demasiado cerca del límite.

POST /api/v1/kyc/age-estimation estima la edad aparente del rostro de un selfi y la compara con una edad mínima. Es la misma comprobación que la opción Comprobación de edad de los formularios (consulte Comprobación de edad), disponible de forma independiente.

El resultado es una estimación a partir de una fotografía, no una prueba de edad. Cada respuesta lo indica (isEstimate, disclaimer). Cerca de su límite, la respuesta es inconclusive por diseño: recurra a una comprobación del documento de identidad.

Autentíquese con una clave de API (Authorization: Bearer ck_live_…) con el ámbito kyc:write. Consulte Autenticación. La fotografía se procesa en memoria y nunca se almacena.

Solicitud

Envíe multipart/form-data o JSON.

curl -X POST https://app.certivant.com/api/v1/kyc/age-estimation \
  -H "Authorization: Bearer $CERTIVANT_API_KEY" \
  -H "Idempotency-Key: signup-8841" \
  -F image=@selfie.jpg \
  -F minAge=18 \
  -F buffer=5

{
  "imageBase64": "/9j/4AAQSkZJRg…",
  "minAge": 18,
  "buffer": 5,
  "dateOfBirth": "1990-02-03"
}

Campo	Tipo	Notas
`image` / `imageBase64`	archivo / string	Un selfi frontal con una única cara. JPEG, PNG, WebP o HEIC, de hasta 10 MB. Se acepta una URL `data:`
`minAge`	entero de 1 a 120, opcional	Por defecto, el ajuste de su organización (Configuración → Prevención de fraude), inicialmente 18
`buffer`	entero de 0 a 30, opcional	Años a cada lado de `minAge` dentro de los cuales no se confía en la estimación. Por defecto, el ajuste de su organización, inicialmente 5
`dateOfBirth`	`YYYY-MM-DD`, opcional	La fecha de nacimiento de un documento de identidad que ya haya verificado. Se usa cuando la estimación no es concluyente

Envíe una cabecera Idempotency-Key para que un reintento no tenga coste: la misma clave se cobra una sola vez.

Respuesta

{
  "data": {
    "result": "pass",
    "method": "estimate",
    "minAge": 18,
    "buffer": 5,
    "isEstimate": true,
    "estimatedAge": 31.4,
    "estimateSpread": 3.2,
    "estimateConfidence": "high",
    "disclaimer": "An estimate from a photo, not proof of age.",
    "chargedCents": 7
  }
}

Campo	Notas
`result`	`pass`, `fail` o `inconclusive`
`method`	`estimate`: decidió el selfi; `id_document`: decidió `dateOfBirth`; `none`: nada pudo decidir
`isEstimate`	Verdadero cuando la estimación del selfi forma parte de la respuesta
`estimatedAge`, `estimateSpread`, `estimateConfidence`	La estimación en años, su grado de incertidumbre y `high` o `low`. Presentes cuando se hizo una estimación
`idAge`	Edad en años completos a partir de `dateOfBirth`, cuando se utilizó
`fallbackReason`	Por qué se necesitó el documento de identidad: `near_limit`, `low_confidence`, `no_estimate` o `estimate_mismatch`
`mismatch`	Una estimación segura y el documento de identidad no coinciden. Trátelo como un caso para revisión manual
`idCheckRequired`	Verdadero cuando el resultado es `inconclusive` y no envió `dateOfBirth`: realice una comprobación del documento de identidad y vuelva a llamar con la fecha de nacimiento, o remita a la persona a una verificación
`disclaimer`	Siempre presente. Muéstrelo siempre que muestre la estimación
`chargedCents`	Lo que costó esta llamada

Cómo se decide

Estimación igual o superior a minAge + buffer → pass.
Estimación inferior a minAge − buffer → fail.
Entre ambos valores, o si el modelo no está seguro de su estimación → decide dateOfBirth si la envió. Sin ella, el resultado es inconclusive.
Cuando envía un dateOfBirth y contradice claramente la estimación, mismatch es true: una estimación muy por encima del límite con una fecha de nacimiento de menor de edad es un fail (gana la fecha de nacimiento); una estimación muy por debajo del límite con una fecha de nacimiento de adulto es inconclusive, para que una persona lo revise.

Errores

Estado	Cuándo
`400`	Imagen, `minAge`, `buffer` o `dateOfBirth` ausentes o no válidos
`402`	Crédito insuficiente para realizar la comprobación
`403`	La estimación de edad no está incluida en su plan
`413`	Imagen de más de 10 MB
`415`	Tipo de imagen no admitido
`422`	No se encontró ninguna cara utilizable (y no hay `dateOfBirth` como respaldo)
`502`	El servicio de estimación no está disponible. Reintente con la misma `Idempotency-Key`

Cuando no se encuentra ninguna cara pero envió un dateOfBirth, la llamada responde igualmente a partir del documento de identidad (method: "id_document").

Facturación

La estimación de edad es una función del plan, con una cuota mensual incluida y un precio de pago por uso por comprobación, descontado de su saldo de crédito. Una llamada que devuelve 402 o 403 no se cobra. Cada comprobación se registra en su registro de auditoría (age_estimation.checked) con el resultado y el método, nunca la fotografía ni la fecha de nacimiento.

En una verificación

Cuando un formulario tiene activada la comprobación de edad, la propia verificación contiene el resultado: sus desencadenantes de revisión o descalificadores pueden incluir age_requirement_not_met o age_check_inconclusive, y las políticas y los flujos de trabajo pueden evaluar age.checked, age.result, age.method, age.estimatedAge, age.minimum, age.meetsMinimum y age.mismatch.