Iniciar validación

Inicia una validación documental enviando las fileKeys de los assets previamente subidos al almacenamiento. El servicio responde de inmediato con un transactionId. El resultado se obtiene mediante polling.

El diagnóstico final (APPROVED, DECLINED o DOUBTFUL), el motivo (rejectionReason) y las señales de verificación individuales (diagnostics[]) se detallan en la respuesta de resultado, que incluye el catálogo completo de códigos de razón (general y granular).

Endpoint

POST /document/validate

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	Sí	Identificador de la operación a la que pertenecen los assets, tal como lo devolvió POST /operation. Todas las fileKey de la petición deben nombrar esta misma operación.

Cuerpo de la solicitud

Content-Type: application/json

Cada asset se referencia mediante una clave de rol fija (document_front, document_back, face), con su type de contexto y su fileKey:

Parámetros

Parámetro	Tipo	Requerido	Descripción
document_front	object	Sí	Asset del anverso del documento.
document_front.type	string	Sí	TOKEN_FRONT_DOCUMENT.
document_front.fileKey	string	Sí	fileKey devuelta por POST /storage, con la forma {operationId}/TOKEN_FRONT_DOCUMENT, enviada sin modificar.
document_back	object	No	Asset del reverso del documento.
document_back.type	string	No	TOKEN_BACK_DOCUMENT.
document_back.fileKey	string	No	fileKey con la forma {operationId}/TOKEN_BACK_DOCUMENT.
face	object	No	Asset de la selfie del titular.
face.type	string	No	TOKEN_BEST_IMAGE.
face.fileKey	string	No	fileKey con la forma {operationId}/TOKEN_BEST_IMAGE.

El campo type solo admite esos tres contextos, cada uno en su hueco.

Ejemplo de solicitud

{
  "document_front": {
    "type": "TOKEN_FRONT_DOCUMENT",
    "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FRONT_DOCUMENT"
  },
  "document_back": {
    "type": "TOKEN_BACK_DOCUMENT",
    "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BACK_DOCUMENT"
  },
  "face": {
    "type": "TOKEN_BEST_IMAGE",
    "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BEST_IMAGE"
  }
}

La fileKey se envía tal como la devolvió POST /storage, con la forma {operationId}/{CONTEXTO}. Añadirle el contexto por tu cuenta lo deja duplicado y el asset no resuelve.

El type de cada hueco tiene que coincidir con el contexto que declara su fileKey. Si no coinciden, la petición se rechaza con 400.

Document Validation solo admite referencia: su petición no lleva campo source y la cabecera operation-id es obligatoria siempre.

Validaciones de entrada

• document_front es obligatorio, con type = TOKEN_FRONT_DOCUMENT y una fileKey resoluble.

• Si se incluyen document_back o face, su type debe coincidir con el esperado en ese hueco y con el contexto que declara su fileKey.

• consumer-id y operation-id no pueden estar vacíos.

• Cada fileKey debe tener la forma {operationId}/{CONTEXTO}, nombrar la operación declarada en la cabecera, llevar el contexto que corresponde a su hueco y tener un asset realmente almacenado.

• Si la solicitud es inválida (bad request), se rechaza con un error 4xx y no se crea la transacción. Otros fallos al iniciar el procesamiento crean la transacción con status = ERROR.

El formato de la clave y los contextos disponibles están en Storage.

Respuestas

202 Accepted

Parámetros de respuesta

Parámetro	Tipo	Descripción
transactionId	string	Identificador único de la transacción de validación.
status	string	PROCESSED (aceptada correctamente) o ERROR (no se pudo iniciar).
timestamp	string	Marca de tiempo de creación de la transacción en formato ISO 8601.

Ejemplo de respuesta

{
  "transactionId": "1c7d...e9",
  "status": "PROCESSED",
  "timestamp": "2026-06-26T12:00:00.000Z"
}

Otras respuestas

Código	Significado
400	La solicitud no supera las validaciones de entrada: asset obligatorio ausente, type que no coincide con el contexto de la clave, cabecera vacía, clave que no tiene la forma {operationId}/{CONTEXTO}, o contexto que no corresponde a ese hueco. No se crea la transacción.
401	Token ausente, inválido o caducado.
403	El consumer no está aprovisionado con el servicio DOCUMENT_ANTIFRAUD.
404	La operación no existe o pertenece a otro consumer.
409	Un asset referenciado contiene un contenido que ya fue procesado en otra operación.
410	La operación ha caducado.
422	Una fileKey nombra una operación distinta de la declarada en la cabecera, o no hay ningún asset almacenado en ese contexto.
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.
503	La persistencia del servicio no está disponible temporalmente.