Injection Attack Detection (IAD)

Servicio que analiza la captura y determina si el flujo de vídeo fue inyectado en lugar de proceder de la cámara del dispositivo.

Acepta el binario en línea o por referencia al asset TOKEN_BIN_IAD. Un único hueco de asset, interpretado según source.

Endpoint

POST /behavioral/iad

Headers

Nombre	Tipo	Requerido	Descripción
Authorization	string	Sí	Token de consumer en formato Bearer <token>. Ver Autenticación.
consumer-id	string	Sí	Identificador del consumer.
operation-id	string	Condicional	Identificador de la operación a la que pertenecen los assets referenciados. Requerido cuando source es FILE_KEY. Ver Storage.

Cuerpo de la solicitud

Content-Type: application/json

Parámetros

Parámetro	Tipo	Requerido	Descripción
source	string	Sí	Modo en que se aportan los assets: FILE_KEY para claves de assets almacenados, FILE para contenido en Base64. Ver Storage.
file	string	Sí	Captura de IAD: clave del asset TOKEN_BIN_IAD o el binario en Base64.
longDetail	boolean	No	Solicita la telemetría del motor en additionalInfo. Por defecto false. Se admite longDetails como nombre alternativo.

Ejemplo de solicitud

{
  "source": "FILE_KEY",
  "file": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BIN_IAD",
  "longDetail": true
}

Respuestas

200 Éxito

Parámetros de respuesta

Parámetro	Tipo	Descripción
consumerId	string	Identificador del consumer que realizó la llamada.
transactionId	string	Identificador de la transacción.
timestamp	string	Marca de tiempo de la respuesta en formato ISO 8601.
message	string	Campo descriptivo del resultado de la ejecución del servicio.
captureLivenessResult	string	Veredicto del servicio: ATTACK cuando la captura se inyectó en lugar de tomarse con la cámara, NO_ATTACK cuando no, y ERROR cuando no se pudo determinar.
reason	string	Motivo del proveedor detrás del veredicto. None cuando la captura se acepta. Ver Motivos de rechazo.
additionalInfo	object	Telemetría del motor. Solo se devuelve si la solicitud la pidió con longDetail. Ver Telemetría del motor.

Ejemplo de respuesta

{
  "consumerId": "consumer-web",
  "transactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486",
  "timestamp": "2026-06-26T12:00:05.000Z",
  "message": "OK",
  "captureLivenessResult": "ATTACK",
  "reason": "UntrustedContent",
  "additionalInfo": {
    "id": "6f3b2c18-91a4-4d77-bb02-0c5e9d8a1f36",
    "score": 0.2,
    "probability": 0.2,
    "captureStartTimestamp": "2026-06-26T12:00:01.420Z",
    "captureEndTimestamp": "2026-06-26T12:00:04.870Z"
  }
}

Sin longDetail, el campo additionalInfo llega a null y el resto de la respuesta es idéntico.

Motivos de rechazo

reason toma uno de estos valores:

Valor	Significado
None	La captura se aceptó como Live.
UntrustedContent	Se detectó un ataque de inyección.
UntrustedContentLowConfidence	Hay indicios de ataque de inyección con menor confianza. La captura se rechaza igualmente.
UntrustedEnvironment	El entorno de ejecución no se considera de confianza.
UntrustedDevice	No se pudo confiar en que el dispositivo fuera el que dice ser.
UntrustedCorruptedPayload	La captura parece corrupta o manipulada.
SuspiciousActivity	El dispositivo mostró patrones de actividad asociados a un ataque.
SdkIntegrityViolation	El SDK de captura o sus bibliotecas parecen haber sido alterados.
Unknown	El motor no pudo asignar la respuesta a ninguno de los motivos anteriores.

Una captura rechazada por la mitigación de reenvío devuelve reason con el valor Replay attack detected, que queda fuera de esta lista.

Telemetría del motor

Con longDetail a true, la respuesta puede incluir additionalInfo con estas claves:

Clave	Descripción
id	Identificador opaco del registro de telemetría del proveedor. Útil para citarlo al escalar una captura.
score	Cifra del veredicto calculada por el motor.
probability	Cifra del veredicto calculada por el motor.
captureStartTimestamp	Inicio de la ventana de captura, según lo informa el SDK de captura.
captureEndTimestamp	Fin de la ventana de captura, según lo informa el SDK de captura.

Pedir la telemetría no garantiza recibirla: additionalInfo llega a null cuando no había registro disponible para esa petición, y cada clave se omite de forma independiente si el motor no la informó. No condicione su integración a que venga.

Al almacenar un TOKEN_BIN_IAD con Save Asset queda disponible además el contexto TOKEN_BEST_IMAGE de la misma operación, de modo que una sola llamada deja listos los assets de IAD y de selfie.

Otras respuestas

Código	Descripción
400	Campo obligatorio ausente o valor no admitido; falta la cabecera operation-id habiendo referencias; una clave no tiene la forma {operationId}/{CONTEXTO} o declara un contexto que el hueco no admite; o el motor rechazó la captura antes de emitir un veredicto, en cuyo caso message lleva el código y el detalle, como en FACE_NOT_FOUND: NoneBecauseFaceNotFound.
403	El consumer no está aprovisionado con el servicio CAPTURE_LIVENESS.
404	La operación declarada en operation-id no existe o pertenece a otro consumer.
409	Un asset referenciado contiene un contenido ya procesado en otra operación.
410	La operación declarada en operation-id ha caducado.
422	Una clave nombra una operación distinta de la declarada en operation-id, o el contexto no tiene ningún asset almacenado.
429	El consumer ha superado su límite de tasa de peticiones, o un asset referenciado ha agotado su presupuesto de invocaciones en este endpoint. En el primer caso la respuesta incluye Retry-After, X-RateLimit-Limit y X-RateLimit-Burst, y esperar resuelve; en el segundo no. El servicio subyacente no se invoca y la llamada no se factura.
502	No se pudo contactar con el motor, respondió algo inutilizable, o informó de un fallo de licencia. La captura no llegó a evaluarse y la petición se puede reintentar.
503	El motor no está configurado en este despliegue, de modo que el endpoint no puede atender ninguna petición.

El cuerpo de una respuesta de error tiene la forma descrita en Middleware API v2.