> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/api-rest/midapi-v2/document-services/document-validation/iniciar-validacion.md). # Iniciar validación Inicia una validación documental enviando las `fileKeys` de los assets previamente [subidos al almacenamiento](/api-rest/midapi-v2/document-services/document-validation/subida-de-assets.md). El servicio responde de inmediato con un `transactionId`. El resultado se obtiene mediante [polling](/api-rest/midapi-v2/document-services/document-validation/consultar-estado.md). {% hint style="info" %} 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](/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md), que incluye el **catálogo completo de códigos de razón** (general y granular). {% endhint %} ### Endpoint ``` POST /document/validate ``` ### Headers | Nombre | Tipo | Requerido | Descripción | | ----------------- | ------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Authorization** | string | **Sí** | Token de consumer en formato `Bearer ` (ver [Autenticación](/api-rest/midapi-v2/autenticacion.md)). | | **consumer-id** | string | **Sí** | Identificador del consumer. | | **operation-id** | string | **Sí** | Identificador de la [operación](/api-rest/midapi-v2/operations.md) 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_FACE_IMAGE`. | | `face.fileKey` | string | No | `fileKey` con la forma `{operationId}/TOKEN_FACE_IMAGE`. | El campo `type` solo admite esos tres contextos, cada uno en su hueco. #### Ejemplo de solicitud ```json { "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_FACE_IMAGE", "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FACE_IMAGE" } } ``` {% hint style="warning" %} 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`. {% endhint %} 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](/api-rest/midapi-v2/storage.md). ### 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 ```json { "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. |