> 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.md).

# Document Validation

**Document Validation** es el servicio que analiza el documento de identidad (y, opcionalmente, una selfie) y determina si son auténticos y consistentes entre sí. El servicio se integra como parte del ecosistema de APIs de Facephi.

A partir del documento (y, si se aporta, la selfie), el servicio ejecuta un conjunto de validaciones antifraude y devuelve un diagnóstico único:

* **APPROVED**: el documento (y, en su caso, la correspondencia con la selfie) supera las validaciones.
* **DECLINED**: se detecta una inconsistencia, manipulación o incumplimiento de calidad/formato que impide validar el documento.
* **DOUBTFUL**: el análisis no es concluyente. El documento no se confirma auténtico ni se rechaza, y la decisión queda del lado del consumer. Solo aparece en la modalidad automática.

### Naturaleza asíncrona

Document Validation es un servicio asíncrono: la llamada que inicia la validación no bloquea a la espera del resultado. Responde de inmediato con un identificador de transacción (`transactionId`) y el consumer obtiene el resultado mediante consultas de estado (polling).

### Modalidades del servicio

Document Validation se presta en dos modalidades, que se fijan en el alta del servicio y no se eligen por petición:

* **Automática**: el diagnóstico lo emite íntegramente el motor antifraude de Facephi. Cuando el análisis no llega a una conclusión, la transacción termina con `diagnostic = DOUBTFUL` y su `rejectionReason` correspondiente.
* **Híbrida**: cuando el análisis inicial no es concluyente, el caso pasa por una verificación adicional escalada antes de resolver. El diagnóstico final es **siempre `APPROVED` o `DECLINED`: esta modalidad no devuelve `DOUBTFUL`**. Los códigos de razón 600 a 603 solo aparecen aquí.

Si no sabes cuál tiene tu integración, consúltalo con soporte.

### Flujo de integración

El arranque (token, operación y subida de assets) es el común a todos los servicios que trabajan por referencia y está desarrollado en [Flujo común](/api-rest/midapi-v2/flujo-comun.md). A partir de ahí:

1. Completar los pasos previos del [flujo común](/api-rest/midapi-v2/flujo-comun.md), incluida la [subida de los assets](/api-rest/midapi-v2/document-services/document-validation/subida-de-assets.md) del documento y, opcionalmente, la selfie.
2. [Iniciar la validación](/api-rest/midapi-v2/document-services/document-validation/iniciar-validacion.md) enviando las `fileKeys` obtenidas tal cual, con el `operationId` en la cabecera `operation-id`. El servicio responde de inmediato con un `transactionId`.
3. [Consultar el estado](/api-rest/midapi-v2/document-services/document-validation/consultar-estado.md) de la transacción mediante polling hasta obtener un estado terminal.

```mermaid
sequenceDiagram
    actor C as Consumer
    participant API as Middleware API v2

    Note over C,API: Pasos previos: token, operación y subida de assets (ver Flujo común)

    C->>API: POST /document/validate (fileKeys + operation-id)
    API-->>C: 202 transactionId, status PROCESSED

    loop Polling hasta estado terminal
        C->>API: GET /document/validate/{transactionId}
        API-->>C: status IN_PROGRESS
    end

    C->>API: GET /document/validate/{transactionId}
    API-->>C: COMPLETED + diagnostic + rejectionReason + diagnostics[] + ocr
```

La cadencia de sondeo recomendada está en [Buenas prácticas](/api-rest/midapi-v2/document-services/document-validation/buenas-practicas.md), y el detalle de la respuesta terminal en [Respuesta de resultado](/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md).

{% hint style="info" %}
Document Validation trabaja **exclusivamente por referencia**: no acepta el contenido de los assets en línea. El modelo de referencia común a toda la API está en [Storage](/api-rest/midapi-v2/storage.md).
{% endhint %}

{% hint style="warning" %}
**Cambio de rutas.** La validación documental se publica ahora bajo `/document/validate`. Las rutas anteriores siguen atendiéndose para no romper las integraciones existentes, pero están obsoletas y dejarán de documentarse:

| Ruta anterior              | Ruta actual                              |
| -------------------------- | ---------------------------------------- |
| `POST /daf/validate`       | `POST /document/validate`                |
| `GET /daf/{transactionId}` | `GET /document/validate/{transactionId}` |
| `POST /daf/fraud-report`   | `POST /document/validate/fraud-report`   |

El contrato no cambia: mismas cabeceras, mismo cuerpo de petición y mismas respuestas. Solo cambia la ruta.
{% endhint %}