Referencia común de FaceAuth

La API de FaceAuth se ha trasladado a /v3/face-auth.La estructura de la respuesta, los nombres de los campos y el formato de error difieren del endpoint anterior /v3/faceauth. Para migrar una integración existente, empiece por Migrar desde la API anterior en esta misma página.

Esta página reúne las definiciones que comparten varios endpoints. Cada página de endpoint hace referencia a ellas por su nombre y documenta únicamente lo que cambia en ese endpoint.

Objeto FaceAuthSubmission: lo usan la respuesta de creación de POST, los elementos de items[] de la consulta de lista y la respuesta de la consulta individual.
Respuestas de error: el formato de error común a todos los endpoints.
Migrar desde la API anterior: los cambios necesarios para pasar una integración de /v3/faceauth a /v3/face-auth.

Objeto FaceAuthSubmission

Objeto que contiene la información de un envío de FaceAuth: el resultado de autenticación, la política usada para la decisión y las puntuaciones de la decisión.

Los campos nunca se omiten en las respuestas.Las políticas que no se aplicaron, los resultados que no se recopilaron y los arreglos que no corresponden se devuelven con null en lugar de eliminar la clave. Por lo tanto, el conjunto de claves del cuerpo de la respuesta es siempre el mismo, independientemente del tipo de envío o de la configuración del proyecto, y basta con comprobar value === null: no hacen falta comprobaciones con 'field' in obj ni con undefined.Los campos cuyo tipo incluye nullable son los que pueden ser null.

Campos de nivel superior

string

Clave del envío de FaceAuth. Guárdela: la usan las API de consulta individual, descarga de imagen y eliminación.

string

Resultado de autenticación. Uno de approved o rejected.

string

Momento de creación del envío, en formato RFC 3339 UTC yyyy-MM-dd'T'HH:mm:ss.SSSZ. (Por ejemplo, 2026-08-11T10:09:14.028Z)

string

Modo de envío. form corresponde a la pantalla de Face Auth URL y api a POST /v3/face-auth.

string

ID del envío KYC usado como referencia de comparación.

nullable · string

Momento en que se completó la eliminación, en formato RFC 3339 UTC. Es null en los envíos que no se han eliminado.

object

Política usada para la decisión. Los seis elementos están siempre presentes. Consulte Elementos de policy más abajo.

object

Resultados de la decisión. Los seis campos están siempre presentes. Consulte Campos de result más abajo.

nullable · object

Información complementaria recopilada en la pantalla de Face Auth URL. Consulte Campos de signals más abajo.

nullable · array

Arreglo de cadenas con los motivos de rechazo. Es null en los envíos approved.

nullable · array

Arreglo de cadenas con los códigos de rechazo. Es null en los envíos approved.

La respuesta de creación de POST /v3/face-auth no incluye policy. El resto de campos es idéntico.

Elementos de policy

Instantánea de la configuración del proyecto en el momento del procesamiento. Cambiar después la configuración del proyecto no altera los valores de los envíos ya creados. Los seis elementos (faceSimilarity, occluded, faceCover, headCover, liveness, activeLiveness) tienen los dos campos siguientes.

boolean

Indica si esta política estaba activada cuando se procesó el envío. Determine si una política se aplicó a partir de este valor, no de threshold.

nullable · number

Criterio numérico usado para la decisión. Es null cuando enabled es false o cuando la política no usa un criterio numérico.

Elemento	Política	Condición de aprobación
`faceSimilarity`	Similitud facial	`result.faceSimilarity` es igual o superior a `threshold`
`occluded`	Prohibición de cubrir el rostro	El rostro no está cubierto. No usa criterio numérico, por lo que `threshold` es siempre `null`
`faceCover`	Equipo de protección facial obligatorio	Se detecta mascarilla, gafas u otro equipo con una confianza igual o superior a `threshold`
`headCover`	Equipo de protección de cabeza obligatorio	Se detecta casco u otro equipo con una confianza igual o superior a `threshold`
`liveness`	Passive Liveness	`result.livenessScore` es igual o superior a `threshold`
`activeLiveness`	Active Liveness	`result.activeLivenessScore` es igual o superior a `threshold`. Solo se ejecuta en envíos `submitType: form`

occluded y faceCover / headCover tienen propósitos opuestos.occluded prohíbe cubrir el rostro, mientras que faceCover y headCover exigen llevar equipo de protección. Los nombres se parecen, pero las condiciones de aprobación son inversas. Estas dos últimas existen para entornos como los industriales, donde el equipo de protección es obligatorio.

enabled es un ajuste del proyecto, no un resultado de ejecución.Una política activada puede no ejecutarse según el modo de envío. Si realmente se ejecutó se determina con el campo correspondiente de result: null significa que no se ejecutó. Hoy la única diferencia de este tipo aparece en activeLiveness. Un envío submitType: api devuelve result.activeLivenessScore como null incluso con enabled: true, y es el comportamiento esperado.

Campos de result

El campo de resultado de una política que no se ejecutó es null. Por ejemplo, un envío con policy.liveness.enabled en false tiene livenessScore como null.

nullable · number

Puntuación de similitud facial, entre 0 y 100 inclusive. Puede incluir decimales.

nullable · number

Puntuación de Passive Liveness.

nullable · number

Puntuación de Active Liveness. Siempre es null en los envíos submitType: api.

nullable · object

Resultado de la detección de rostro cubierto. value: true significa que se consideró cubierto y el envío se rechazó.

Mostrar Properties

nullable · boolean

Si se detectó o no.

nullable · number

Confianza de la decisión, entre 0 y 100 inclusive.

nullable · object

Resultado de la detección de equipo de protección facial. value: false significa que se consideró no llevado y el envío se rechazó. Sus propiedades son las mismas que las de occluded.

nullable · object

Resultado de la detección de equipo de protección de cabeza. value: false significa que se consideró no llevado y el envío se rechazó. Sus propiedades son las mismas que las de occluded.

occluded, faceCover y headCover comparten la misma estructura. Cuando la comprobación no se ejecutó, el objeto completo es null: nunca se devuelve con solo sus propiedades en null.

Campos de signals

Información complementaria recopilada en la pantalla de Face Auth URL. Solo los envíos submitType: form con valores recopilados contienen datos aquí; en los envíos submitType: api y en aquellos sin valores recopilados el objeto completo es null. Es informativa y no se usa para la decisión de autenticación.

nullable · string

Momento en que el usuario pulsó el botón de inicio, en formato RFC 3339 UTC.

nullable · array

Registro de los tramos de captura de cámara. Cuando no hay registro es null, no un arreglo vacío.

Mostrar Properties

nullable · string

Momento de inicio del tramo de captura, en formato RFC 3339 UTC.

nullable · string

Momento de fin del tramo de captura, en formato RFC 3339 UTC.

nullable · string

Tipo de tramo de captura, como faceAuth-passive, faceAuth-active o faceAuth-auto-capture. La lista de valores no es fija y puede ampliarse sin previo aviso, así que ignore los valores que no reconozca.

nullable · string

Error ocurrido en ese tramo, o null si no hubo ninguno. El mensaje se recopila en el navegador del usuario y no tiene un formato fijo, así que no lo use para bifurcar la lógica.

rejectComment y failCode

rejectComment es una explicación legible por personas; failCode es el código sobre el que bifurcar.

Bifurque con failCode, no con rejectComment. El texto de rejectComment cambia sin previo aviso y causas distintas comparten a veces el mismo texto. Please retry with another face image. lo usan tanto liveness_fail como active_liveness_fail.

Los dos arreglos se corresponden índice a índice y tienen siempre la misma longitud. El motivo de failCode[0] es rejectComment[0].

result.json

{
  "rejectComment": [
    "Protection equipment is not found on Head.",
    "face compare similarity score is lower than threshold"
  ],
  "failCode": ["Head_cover_fail", "face_compare_underscore"]
}

Un mismo envío puede incumplir varias políticas a la vez, así que revise todos los valores del arreglo. El orden sigue el de evaluación de las políticas y no es fijo: no dé por supuesto que un código concreto aparece siempre primero. Para la lista de valores de failCode, consulte POST /v3/face-auth.

Notas para el procesamiento de respuestas

El conjunto de claves de una respuesta es siempre el mismo. Los valores ausentes llegan como null, así que no hacen falta comprobaciones de undefined ni de existencia de clave.
0 es un valor válido para policy.*.threshold. No use una comprobación de tipo falsy para decidir si una política está configurada: use enabled.
Los campos de tipo arreglo son null, no un arreglo vacío, cuando no hay valor. Aplique un valor por defecto con ?? [] o compruebe !== null antes de recorrerlos.
Los objetos anidados (occluded, faceCover, headCover, signals) son null en su totalidad cuando no corresponden. Compruebe si el padre es null antes de leer sus propiedades.
Cuando el umbral y la puntuación son iguales, se considera que el umbral se cumple.
Las puntuaciones pueden incluir decimales en lugar de ser enteros. Procéselas como números, no como cadenas.

Respuestas de error

Los errores que devuelve la aplicación de ARGOS usan el formato siguiente.

error.json

{
  "code": "REQUEST_INVALID",
  "message": "limit must be a decimal integer between 10 and 200."
}

string

Código de error. Bifurque con este valor y no con el código de estado HTTP.

string

Descripción legible por personas. El texto puede cambiar sin previo aviso, así que nunca bifurque comparando cadenas.

El objeto de error tiene exactamente dos campos: code y message.

Errores de la capa de autenticación (401, 403)

Las solicitudes bloqueadas en la capa de autenticación no siguen el formato { code, message }.La validación de la clave API ocurre en la capa de autenticación, antes de que la solicitud llegue a la aplicación de ARGOS. Las respuestas bloqueadas en esa fase no tienen campo code.

Situación	Estado HTTP	Cuerpo de la respuesta
No se envía clave API	`401`	`{ "message": "Unauthorized" }`
Clave API inexistente o no válida	`403`	`{ "message": "..." }`
Clave API válida pero no vinculada a un proyecto FaceAuth	`403`	`{ "code": "AUTH_FORBIDDEN", "message": "..." }`

Trate el 401 y el 403 de la capa de autenticación por estado HTTP, no por code. Ninguna de las dos respuestas tiene campo code.
El 403 tiene dos causas con formatos de respuesta distintos. Si hay campo code, lo devolvió la aplicación; si no lo hay, lo bloqueó la capa de autenticación.
El message de un error de la capa de autenticación no lo genera ARGOS y puede cambiar sin previo aviso. No lo procese.

Al notificar una consulta técnica o una incidencia, incluya la hora de la solicitud (UTC), el endpoint invocado y los cuatro primeros caracteres de la clave API utilizada.

Lista de códigos de error

Estado HTTP	code	Condición	Endpoints
`400`	`REQUEST_INVALID`	La solicitud no es válida. Consulte la sección de errores de cada página de endpoint.	Todos
`400`	`FACEAUTH_FACE_NOT_DETECTED`	No se encontró un rostro comparable en la imagen facial.	POST
`403`	`AUTH_FORBIDDEN`	La clave API es válida pero no está vinculada a un proyecto FaceAuth.	Todos
`404`	`FACEAUTH_SUBMISSION_NOT_FOUND`	No se encuentra el `authId` en este proyecto.	Consulta individual, imagen, DELETE
`404`	`SUBMISSION_NOT_FOUND`	El envío KYC no existe, se eliminó o pertenece a otro proyecto.	POST
`409`	`SUBMISSION_NOT_APPROVED`	El envío KYC no está aprobado o no tiene imagen de referencia.	POST
`503`	`UPSTREAM_UNAVAILABLE`	Un servicio interno no está disponible temporalmente. Reintente la misma solicitud en unos instantes.	Todos
`503`	`UPSTREAM_INVALID_RESPONSE`	El resultado interno de la consulta no puede convertirse al contrato público.	Consulta de lista e individual
`500`	`INTERNAL_UNEXPECTED`	Error inesperado del servidor.	Todos

Migrar desde la API anterior

Si su integración usa el endpoint anterior /v3/faceauth, revise los cambios siguientes. Han cambiado las rutas, los nombres de los campos, los sobres de respuesta y el formato de error.

Endpoints

Operación	API anterior	API nueva
Crear un envío	`POST /v3/faceauth`	`POST /v3/face-auth`
Consulta de lista	`GET /v3/faceauth`	`GET /v3/face-auth`
Consulta individual	`GET /v3/faceauth?authId=...`	`GET /v3/face-auth/{authId}`
Descarga de imagen	`GET /v3/faceauth/image?authId=...`	`GET /v3/face-auth/{authId}/image`
Eliminar un envío	`DELETE /v3/faceauth?authId=...`	`DELETE /v3/face-auth/{authId}`

authId pasa a ser un parámetro de ruta en lugar de un parámetro de consulta, y la consulta de lista y la individual son endpoints separados.

Sobres de respuesta

Caso	API anterior	API nueva
Consulta individual	`{ faceAuth_projectId, data: [ {...} ] }`	El objeto del envío en el nivel superior
Consulta de lista	`{ faceAuth_projectId, data: { items, nextPage_key } }`	`{ items, nextCursor }`
`authId` inexistente	`200` con `data: []`	`404 FACEAUTH_SUBMISSION_NOT_FOUND`
Crear un envío	`200` con `{ score, authentication_id, ... }`	`201 Created` con el objeto FaceAuthSubmission
Eliminar un envío	`{ "result": "success", "statusCode": 200 }`	`{ "authId": "..." }`

faceAuth_projectId y statusCode se han eliminado de las respuestas.

Nombres de campos

API anterior	API nueva
`auth_id` / `authentication_id` (POST)	`authId`
`auth_status`	`authStatus`
`create_time`	`createTime`
`submit_type`	`submitType`
`kyc_submission_id`	`kycSubmissionId`
`reject_comment` / `rejected_comment` (POST)	`rejectComment`
`fail_code`	`failCode`
`score` (POST, snake_case)	`result` (camelCase, igual que en las consultas)
`delete_check` + `delete_time`	Solo `deleteTime` (`null` antes de eliminar)

Cambios estructurales

policy: de umbrales planos a objetos anidados

La API anterior llevaba los umbrales planos, como en faceSimilarity_threshold: 85, y solo occluded_threshold era un boolean.La API nueva da a cada elemento un objeto { enabled, threshold }. Si una política se aplicó se determina con enabled, no con el valor de threshold. occluded no usa criterio numérico, así que su threshold es siempre null.

API anterior

{ "faceSimilarity_threshold": 85, "occluded_threshold": true }

API nueva

{
  "faceSimilarity": { "enabled": true, "threshold": 85 },
  "occluded": { "enabled": true, "threshold": null }
}

result: occluded, faceCover y headCover pasan a ser objetos

La API anterior devolvía un único valor, como occluded: false (boolean) o headCover: 0 (number). En la API nueva los tres son objetos { value, confidence }, y el objeto completo es null cuando la comprobación no se ejecutó.

API nueva

{ "occluded": { "value": false, "confidence": 99.2 }, "faceCover": null }

Paginación: de una clave compuesta a un único cursor

La API anterior devolvía nextPage_key y esperaba de vuelta su authId y su createTime como nextKey_id y nextKey_date, con el tamaño de página en count (1–2.000, valor predeterminado 2.000).La API nueva devuelve una única cadena firmada, nextCursor, que se reenvía tal cual en cursor, con el tamaño de página en limit (10–200, valor predeterminado 100). Un limit fuera de rango ya no se ignora: devuelve 400 REQUEST_INVALID.

Descarga de imagen: del cuerpo binario a una redirección 302

La API anterior devolvía el binario JPEG directamente en el cuerpo de la respuesta. La API nueva devuelve 302 Found con una URL de descarga de vida corta en el encabezado Location, así que el cliente HTTP debe estar configurado para seguir redirecciones (curl --location).

Formato de error: de tres formatos a uno

La API anterior mezclaba { message, errorCode, statusCode }, { traceId, errorCode, message } y { message, statusCode } según el endpoint, y el endpoint de imagen devolvía 403 para cualquier fallo de autenticación.La API nueva devuelve todos los errores de aplicación como { code, message }, con los errores de la capa de autenticación como única excepción. Consulte Respuestas de error más arriba.

El cambio que más conviene vigilar

La API anterior eliminaba de la respuesta las claves de las opciones no utilizadas; la API nueva incluye siempre la clave y rellena el valor con null.El código escrito para la API anterior que decide si una política se usó a partir de la existencia de la clave — if (result.headCover) o 'headCover' in result — funciona mal con la API nueva. Use result.headCover !== null (si se ejecutó) o policy.headCover.enabled (si está configurada) en su lugar.

​Objeto FaceAuthSubmission

​Campos de nivel superior

​Elementos de policy

​Campos de result

​Campos de signals

​rejectComment y failCode

​Notas para el procesamiento de respuestas

​Respuestas de error

​Errores de la capa de autenticación (401, 403)

​Lista de códigos de error

​Migrar desde la API anterior

​Endpoints

​Sobres de respuesta

​Nombres de campos

​Cambios estructurales

​El cambio que más conviene vigilar

Objeto FaceAuthSubmission

Campos de nivel superior

Elementos de policy

Campos de result

Campos de signals

rejectComment y failCode

Notas para el procesamiento de respuestas

Respuestas de error

Errores de la capa de autenticación (401, 403)

Lista de códigos de error

Migrar desde la API anterior

Endpoints

Sobres de respuesta

Nombres de campos

Cambios estructurales

El cambio que más conviene vigilar